X-Git-Url: https://wannabe.guru.org/gitweb/?a=blobdiff_plain;f=docs%2Fpyutils.rst;h=eb839075ce8b6c69b8fc7b84df8424f2fd19e9d3;hb=e699089d766afa2ac4e665724160a12d28d4ade7;hp=9186f95ee81765b89bea7543de1dc7ce73a384db;hpb=40a9cba91b25d099470c63840f90aac33cca852e;p=pyutils.git diff --git a/docs/pyutils.rst b/docs/pyutils.rst index 9186f95..eb83907 100644 --- a/docs/pyutils.rst +++ b/docs/pyutils.rst @@ -1,35 +1,71 @@ pyutils package =============== +Introduction +------------ + When I was writing little tools in Python and found myself implementing a generally useful pattern I stuffed it into a local library. That library grew into pyutils: a set of collections, helpers and utilities that I find useful and hope you will too. -Code is under `src/pyutils/ +The `LICENSE +`__ +and `NOTICE +`__ +files at the root of the project describe reusing this code and where +everything came from. Drop me a line if you are using this, find a +bug, have a question, or have a suggestion: + + --Scott Gasch (scott.gasch@gmail.com) + +Installation +------------ + +This project is now *pyutils* in PyPi, the default Python project index. To install +with pip:: + + pip install pyutils + +You'll get a few dependencies and this library. The dependencies are high quality and +stable: + + - antlr4-python3-runtime: ANTLR grammer/parser runtime dependencies for the date + parsing grammar. + - bitstring: easy bitwise operations on long operands + - cloudpickle: a better version of Python's built in pickle used in the parallelize + code. + - holidays: a list of US and international holidays, used in the date parser. + - kazoo: a client side library with recipes for working with Apache Zookeeper, used + if and only if you enable Zookeeper-based configs. + - overrides: code decorator to mark and enforce method overrides. + - pytz: Python timezones, used in date parser and utils. + +Development +----------- + +All of the project's code is located under `src/pyutils/ `_. -Most code includes inlint documentation and doctests. I've tried to +Most code includes inline documentation and doctests. I've tried to organize it into logical packages based on the code's functionality. -Note that when words would collide with a Python library or reserved -word I've used a 'z' at the end, e.g. 'collectionz' instead of -'collections', 'typez' instead of 'type', etc... +Note that when words would collide with a Python standard library or +reserved keyword I've used a 'z' at the end, e.g. 'collectionz' +instead of 'collections'. There's some example code that uses various features of this project checked -in under `examples/ `_ that you can check out. +in under `examples/ `_ that you can check out. See the `README `__ in that directory for more information +about what's there. Unit and integration tests are under `tests/ `_. + To run all tests:: cd tests/ ./run_tests.py --all [--coverage] -See the `README `_ under `tests/` and the code of `run_tests.py` for more -options / information about running tests. - -This package generates Sphinx docs which are available at: - - https://wannabe.guru.org/pydocs/pyutils/pyutils.html +See the `README `__ +under `tests/` and the code of `run_tests.py` for more options / information about running tests. Package code is checked into a local git server and available to clone from git at https://wannabe.guru.org/git/pyutils.git or to view in a @@ -43,16 +79,31 @@ development happened in a different git repo: https://wannabe.guru.org/gitweb/?p=python_utils.git;a=summary -The `LICENSE -`__ -and `NOTICE -`__ -files at the root of the project describe reusing this code and where -everything came from. Drop me a line if you are using this, find a -bug, have a question, or have a suggestion: +To actually build the code (by which I mean type check it, lint it, package it, format +it, etc...) you need some other dependencies installed: - --Scott Gasch (scott.gasch@gmail.com) + - black: I use black to auto-format the code + - mypy: a Python type checker + - coverage: used by the --coverage option of `run_tests.py`. + - flake8: a Python linter + - pylint: another Python linter + - sphinx: documenation generator + - setuptools: to build the project artifacts + - twine: to package and upload packages + +Documentation +------------- +The documentation you're browsing was created by Sphinx based largely on extracted code comments. +It's available at: + + https://wannabe.guru.org/pydocs/pyutils/pyutils.html + +Support +------- + +If you find a bug or have a question, please email me (scott.gasch@gmail.com). I have not +yet set up any more official bug tracker because there's no need yet. Subpackages ----------- @@ -63,12 +114,12 @@ Subpackages pyutils.collectionz pyutils.compress - pyutils.datetimez + pyutils.datetimes pyutils.files pyutils.parallelize pyutils.search pyutils.security - pyutils.typez + pyutils.types Submodules ---------- @@ -2220,6 +2271,14 @@ during runtime) via Zookeeper (which is disabled by default). :undoc-members: :show-inheritance: +pyutils.dataclass\_utils module +------------------------------- + +.. automodule:: pyutils.dataclass_utils + :members: + :undoc-members: + :show-inheritance: + pyutils.decorator\_utils module -------------------------------