From 6e7ee87b17b87abb3b598d39da6b4eed2c8e7697 Mon Sep 17 00:00:00 2001 From: Scott Gasch Date: Tue, 25 Oct 2022 09:47:09 -0700 Subject: [PATCH] Update documentation. --- docs/pyutils.rst | 90 +++++++++++++++++++++++++++++++++++++----------- tests/README | 9 ++--- 2 files changed, 75 insertions(+), 24 deletions(-) diff --git a/docs/pyutils.rst b/docs/pyutils.rst index 9186f95..0836f31 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', 'typez' instead of 'type', etc... 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,30 @@ 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 + - 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 ----------- diff --git a/tests/README b/tests/README index 4553b73..ab2729b 100644 --- a/tests/README +++ b/tests/README @@ -2,7 +2,7 @@ This directory contains the (non-doctest) testcode for pyutils (i.e. unit tests and integration tests). It also contains a couple of helpers to run the tests. -The easiest way to run the tests is, from within this tests/ directory, run: +The easiest way to run the tests is, from within this tests/ directory, to run: ./run_tests_serially.sh -a @@ -19,11 +19,12 @@ Or: ./run_tests.py -d -Both of these runners store test output under ./test_output. +Both of these runners store test output under tests/test_output. Both of them can optionally use coverage (pip install coverage) to generate a -code coverage report: +code coverage report at the end of testing: ./run_tests.py --all --coverage -I use ./run_tests.py --all --coverage as a .git/hooks/pre-commit-hook. +I use ./run_tests.py --all --coverage as a .git/hooks/pre-commit-hook during +development. -- 2.45.2