NPO-Accounting/conservancy_beancount
6
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

doc: Document installation into a virtualenv.

Browse source
This commit is contained in:
Ben Sturmfels 2022-02-04 19:26:31 +11:00
parent 9c69d656a3
commit dd35ed25c2
Signed by: bsturmfels
GPG key ID: 023C05E2C9C068F0
2 changed files with 19 additions and 2 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
README.rst
View file

@ -17,7 +17,7 @@ Installation
python3 -m pip install --user --upgrade .
Of course, if you're familiar with Python development tools, you're welcome to install the module in a virtualenv, somewhere else, etc.
For development, a Python virtual environment may be more appropriate. See the development documentation for details.
Development
-----------

19
doc/Development.rst
View file

@ -11,6 +11,17 @@ The project comes with a Tox configuration that defines all the tests we expect
The next sections describe how to run them standalone in your own development environment, for faster iteration or simpler isolation of problems.
Installing
~~~~~~~~~~
Create a virtual environment, for example::
python3 -m venv ~/.virtualenvs/conservancy-beancount
Install the ``conservancy_beancount`` as an editable package including the test dependencies::
~/.virtualenvs/conservancy-beancount/bin/python -m pip install --editable ~/conservancy/conservancy_beancount[test]
Running unit tests
~~~~~~~~~~~~~~~~~~
@ -18,11 +29,17 @@ Run::
pytest
Alternatively, you can run ``tox`` which will run the tests in a clean virtual
environment with all the relevant dependencies.
Type checking
~~~~~~~~~~~~~
Most of the code is typed, except for very dynamic loader methods. To run the type checker::
# Beancount includes type declarations but not the `py.typed` flag file mypy
# is looking for to know that. Create it ourselves.
python -c 'import beancount, pathlib; pathlib.Path(beancount.__file__).with_name("py.typed").touch()'
mypy conservancy_beancount
This is expected to pass just like the unit tests.
@ -34,7 +51,7 @@ Books that use this plugin are expected to say::
plugin "conservancy_beancount.plugin"
When Beancount sees this directive after loading all the data, it passes everything it loaded through the ``run`` function in ``conservancy_beancount/plugin/__init__.py`` to be manipulated. Our ``run`` function, it turn, passes the data through hooks defined in other files under ``conservancy_beancount/plugin`` to normalize data and report errors. ``HookRegistry`` in ``__init__.py`` is the bridge between these two. It supports dynamically choosing which hooks are loaded at runtime, although we currently aren't using that.
When Beancount sees this directive after loading all the data, it passes everything it loaded through the ``run`` function in ``conservancy_beancount/plugin/__init__.py`` to be manipulated. Our ``run`` function, in turn, passes the data through hooks defined in other files under ``conservancy_beancount/plugin`` to normalize data and report errors. ``HookRegistry`` in ``__init__.py`` is the bridge between these two. It supports dynamically choosing which hooks are loaded at runtime, although we currently aren't using that.
``conservancy_beancount/plugin/core.py`` has the base classes for these hooks. The rest of the files in the directory contain the specific hooks that are loaded and run. All the ``meta_foo.py`` files have hook(s) to validate ``foo`` metadata. ``txn_date.py`` verifies that transactions are in the right file by fiscal year.