docs/pyutils.rst

   1 pyutils package
   2 ===============
   3
   4 When I was writing little tools in Python and found myself implementing
   5 a generally useful pattern I stuffed it into a local library.  That
   6 library grew into pyutils: a set of collections, helpers and utilities
   7 that I find useful and hope you will too.
   8
   9 Code is under `src/pyutils/`.  Most code includes documentation and inline
  10 doctests.
  11
  12 Unit and integration tests are under `tests/*`.  To run all tests::
  13
  14     cd tests/
  15     ./run_tests.py --all [--coverage]
  16
  17 See the README under `tests/` and the code of `run_tests.py` for more
  18 options / information.
  19
  20 This package generates Sphinx docs which are available at:
  21
  22     https://wannabe.guru.org/pydocs/pyutils/pyutils.html
  23
  24 Package code is checked into a local git server and available to clone
  25 from git at https://wannabe.guru.org/git/pyutils.git or from a web browser
  26 at:
  27
  28     https://wannabe.guru.org/gitweb/?p=pyutils.git;a=summary
  29
  30 For a long time this was just a local library on my machine that my
  31 tools imported but I've now decided to release it on PyPi.  Early
  32 development happened in a different git repo:
  33
  34     https://wannabe.guru.org/gitweb/?p=python_utils.git;a=summary
  35
  36 I hope you find this useful.  LICENSE and NOTICE describe reusing it
  37 and where everything came from.  Drop me a line if you are using this,
  38 find a bug, or have a question:
  39
  40   --Scott Gasch ([email protected])
  41
  42
  43 Subpackages
  44 -----------
  45
  46 .. toctree::
  47    :maxdepth: 4
  48
  49    pyutils.collectionz
  50    pyutils.compress
  51    pyutils.datetimez
  52    pyutils.files
  53    pyutils.parallelize
  54    pyutils.search
  55    pyutils.security
  56    pyutils.typez
  57
  58 Submodules
  59 ----------
  60
  61 pyutils.ansi module
  62 -------------------
  63
  64 This file mainly contains code for changing the nature of text printed
  65 to the console via ANSI escape sequences.  e.g. it can be used to emit
  66 text that is bolded, underlined, italicised, colorized, etc...
  67
  68 It also contains a colorizing context that will apply color patterns
  69 based on regular expressions to any data emitted to stdout that may be
  70 useful in adding color to other programs' outputs, for instance.
  71
  72 .. automodule:: pyutils.ansi
  73    :members:
  74    :undoc-members:
  75    :show-inheritance:
  76
  77 pyutils.argparse\_utils module
  78 ------------------------------
  79
  80 I use the Python internal `argparse` module for commandline argument
  81 parsing but found it lacking in some ways.  This module contains code to
  82 fill those gaps.  It include stuff like:
  83
  84     - An `argparse.Action` to create pairs of flags such as
  85       `--feature` and `--no_feature`.
  86     - A helper to parse and validate bools, IP addresses, MAC
  87       addresses, filenames, percentages, dates, datetimes, and
  88       durations passed as flags.
  89
  90 .. automodule:: pyutils.argparse_utils
  91    :members:
  92    :undoc-members:
  93    :show-inheritance:
  94
  95 pyutils.bootstrap module
  96 ------------------------
  97
  98 Bootstrap module defines a decorator meant to wrap your main function.
  99 This decorator will do several things for you:
 100
 101     - If your code uses the :file:`config.py` module (see below), it invokes
 102       `parse` automatically to initialize `config.config` from commandline
 103       flags, environment variables, or other sources.
 104     - It will optionally break into pdb in response to an unhandled
 105       Exception at the top level of your code.
 106     - It initializes logging for your program (see :file:`logging.py`).
 107     - It can optionally run a code and/or memory profiler on your code.
 108
 109 .. automodule:: pyutils.bootstrap
 110    :members:
 111    :undoc-members:
 112    :show-inheritance:
 113
 114 pyutils.config module
 115 ---------------------
 116
 117 This module reads the program's configuration parameters from: the
 118 commandline (using argparse), environment variables and/or a shared
 119 zookeeper-based configuration.  It stores this configuration state in
 120 a dict-like structure that can be queried by your code at runtime.
 121
 122 It handles creating a nice `--help` message for your code.
 123
 124 It can optionally react to dynamic config changes and change state at
 125 runtime (iff you name your flag with the *dynamic_* prefix and are
 126 using zookeeper-based configs).
 127
 128 It can optionally save and retrieve sets of arguments from files on
 129 the local disk or on zookeeper.
 130
 131 All of my examples use this as does the pyutils library itself.
 132
 133 .. automodule:: pyutils.config
 134    :members:
 135    :undoc-members:
 136    :show-inheritance:
 137
 138 pyutils.decorator\_utils module
 139 -------------------------------
 140
 141 This is a grab bag of decorators.
 142
 143 .. automodule:: pyutils.decorator_utils
 144    :members:
 145    :undoc-members:
 146    :show-inheritance:
 147
 148 pyutils.dict\_utils module
 149 --------------------------
 150
 151 A bunch of helpers for dealing with Python dicts.
 152
 153 .. automodule:: pyutils.dict_utils
 154    :members:
 155    :undoc-members:
 156    :show-inheritance:
 157
 158 pyutils.exec\_utils module
 159 --------------------------
 160
 161 Helper code for dealing with subprocesses.
 162
 163 .. automodule:: pyutils.exec_utils
 164    :members:
 165    :undoc-members:
 166    :show-inheritance:
 167
 168 pyutils.function\_utils module
 169 ------------------------------
 170
 171 Helper util for dealing with functions.
 172
 173 .. automodule:: pyutils.function_utils
 174    :members:
 175    :undoc-members:
 176    :show-inheritance:
 177
 178 pyutils.id\_generator module
 179 ----------------------------
 180
 181 Generate unique identifiers.
 182
 183 .. automodule:: pyutils.id_generator
 184    :members:
 185    :undoc-members:
 186    :show-inheritance:
 187
 188 pyutils.iter\_utils module
 189 --------------------------
 190
 191 Iterator utilities including a :class:PeekingIterator, :class:PushbackIterator,
 192 and :class:SamplingIterator.
 193
 194 .. automodule:: pyutils.iter_utils
 195    :members:
 196    :undoc-members:
 197    :show-inheritance:
 198
 199 pyutils.list\_utils module
 200 --------------------------
 201
 202 Utilities for dealing with Python lists.
 203
 204 .. automodule:: pyutils.list_utils
 205    :members:
 206    :undoc-members:
 207    :show-inheritance:
 208
 209 pyutils.logging\_utils module
 210 -----------------------------
 211
 212 This is a module that offers an opinionated take on how whole program logging
 213 should be initialized and controlled.  It uses standard Python logging but gives
 214 you control, via commandline config, to:
 215
 216     - Set the logging level of the program including overriding the
 217       logging level for individual modules,
 218     - Define the logging message format including easily adding a
 219       PID/TID marker on all messages to help with multithreaded debugging,
 220     - Control the destination (file, sys.stderr, syslog) of messages,
 221     - Control the facility and logging level used with syslog,
 222     - Squelch repeated messages,
 223     - Log probalistically,
 224     - Clear rogue logging handlers added by other imports.
 225
 226 .. automodule:: pyutils.logging_utils
 227    :members:
 228    :undoc-members:
 229    :show-inheritance:
 230
 231 pyutils.math\_utils module
 232 --------------------------
 233
 234 Helper utilities that are "mathy" such as a :class:NumericPopulation that
 235 makes population summary statistics available to your code quickly, GCD
 236 computation, literate float truncation, percentage <-> multiplier, prime
 237 number determination, etc...
 238
 239 .. automodule:: pyutils.math_utils
 240    :members:
 241    :undoc-members:
 242    :show-inheritance:
 243
 244 pyutils.misc\_utils module
 245 --------------------------
 246
 247 Miscellaneous utilities: are we running as root, and is a debugger attached?
 248
 249 .. automodule:: pyutils.misc_utils
 250    :members:
 251    :undoc-members:
 252    :show-inheritance:
 253
 254 pyutils.persistent module
 255 -------------------------
 256
 257 Persistent defines a class hierarchy and decorator for creating
 258 singleton classes that (optionally/conditionally) load their state
 259 from some external location and (optionally/conditionally) stave their
 260 state to an external location at shutdown.
 261
 262 .. automodule:: pyutils.persistent
 263    :members:
 264    :undoc-members:
 265    :show-inheritance:
 266
 267 pyutils.remote\_worker module
 268 -----------------------------
 269
 270 This module defines a helper that is invoked by the remote executor to
 271 run pickled code on a remote machine.  It is used by code marked with
 272 @parallelize(method=Method.REMOTE) in the parallelize framework.
 273
 274 .. automodule:: pyutils.remote_worker
 275    :members:
 276    :undoc-members:
 277    :show-inheritance:
 278
 279 pyutils.state\_tracker module
 280 -----------------------------
 281
 282 This module defines several classes (:class:StateTracker,
 283 :class:AutomaticStateTracker, and
 284 :class:WaitableAutomaticStateTracker) that can be used as base
 285 classes.  These class patterns are meant to encapsulate and represent
 286 state that dynamically changes.  These classes update their state
 287 (either automatically or when invoked to poll) and allow their callers
 288 to wait on state changes.
 289
 290 .. automodule:: pyutils.state_tracker
 291    :members:
 292    :undoc-members:
 293    :show-inheritance:
 294
 295 pyutils.stopwatch module
 296 ------------------------
 297
 298 This is a stopwatch context that just times how long something took to
 299 execute.
 300
 301 .. automodule:: pyutils.stopwatch
 302    :members:
 303    :undoc-members:
 304    :show-inheritance:
 305
 306 pyutils.string\_utils module
 307 ----------------------------
 308
 309 A bunch of utilities for dealing with strings.  Based on a really great
 310 starting library from Davide Zanotti, I've added a pile of other string
 311 functions so hopefully it will handle all of your string-needs.
 312
 313 .. automodule:: pyutils.string_utils
 314    :members:
 315    :undoc-members:
 316    :show-inheritance:
 317
 318 pyutils.text\_utils module
 319 --------------------------
 320
 321 Utilities for dealing with and creating text chunks.  For example:
 322
 323     - Make a bar graph,
 324     - make a spark line,
 325     - left, right, center, justify text,
 326     - word wrap text,
 327     - indent text,
 328     - create a header line,
 329     - draw a box around some text.
 330
 331 .. automodule:: pyutils.text_utils
 332    :members:
 333    :undoc-members:
 334    :show-inheritance:
 335
 336 pyutils.unittest\_utils module
 337 ------------------------------
 338
 339 Utilities to support smarter unit tests.
 340
 341 .. automodule:: pyutils.unittest_utils
 342    :members:
 343    :undoc-members:
 344    :show-inheritance:
 345
 346 pyutils.unscrambler module
 347 --------------------------
 348
 349 Unscramble scrambled English words quickly.
 350
 351 .. automodule:: pyutils.unscrambler
 352    :members:
 353    :undoc-members:
 354    :show-inheritance:
 355
 356 pyutils.zookeeper module
 357 ------------------------
 358
 359 A helper module for dealing with Zookeeper that adds some functionality.
 360
 361 .. automodule:: pyutils.zookeeper
 362    :members:
 363    :undoc-members:
 364    :show-inheritance:
 365
 366 Module contents
 367 ---------------
 368
 369 .. automodule:: pyutils
 370    :members:
 371    :undoc-members:
 372    :show-inheritance: