rattail/rattail-manual
1
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity

update docs for commands, scripts

Browse source 
per changes regarding typer, wuttjamaican etc.
This commit is contained in:
Lance Edgar 2024-07-01 10:53:58 -05:00
parent 9fa7062f4d
commit 0838cdb93c
2 changed files with 23 additions and 19 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

21
docs/base/commands.rst
View file

@ -16,32 +16,29 @@ root of your virtual environment. For example this command will generate and
display a new UUID::
cd /srv/envs/poser
bin/rattail -c app/quiet.conf make-uuid
Also note that in general, you should always specify a config file as part of
the command line (as shown above).
bin/rattail make-uuid
Getting Help
------------
You can always just add ``-h`` (or ``--help``) to the end of any command line.
This will render the command "inert" and the only thing it will do, is display
some help text.
You can always just add ``--help`` to the end of any command line.
This will render the command "inert" and the only thing it will do, is
display some help text.
Really there are 2 "layers" to the command framework: commands proper, and
subcommands. In the example above, ``bin/rattail`` is the command proper,
and ``make-uuid`` is the subcommand.
To get help on the command proper, add ``-h`` to your command line but omit the
To get help on the command proper, add ``--help`` to your command line but omit the
subcommand, e.g.::
bin/rattail -c app/quiet.conf -h
bin/rattail --help
To get help on a subcommand, you must include the subcommand name as though you
were running it, then also add ``-h`` to the command line::
were running it, then also add ``--help`` to the command line::
bin/rattail -c app/quiet.conf make-uuid -h
bin/rattail make-uuid --help
Usage with ``sudo``
@ -51,7 +48,7 @@ If your virtual environment is owned by someone other than yourself, then you
probably should run commands as that user also::
cd /srv/envs/poser
sudo -u rattail bin/rattail -c app/quiet.conf make-uuid
sudo -u rattail bin/rattail make-uuid
Among other things this may be necessary so that:

21
docs/base/scripts.rst
View file

@ -25,6 +25,8 @@ Python Scripts
A "complete" sample Python script is shown below. It may be more complex than
you typically need, but hopefully not too bad; modify as you like.
(See also :doc:`wuttjamaican:narr/cli/scripts` for more simple examples.)
If you use :doc:`/data/versioning` then it is important to "postpone" most
module imports, until the config has been fully created. (Even if you don't
use versioning it's a good habit, in case you ever change your mind.) This is
@ -44,14 +46,21 @@ main function, instead of at the top of the script.
def do_something(config):
# most imports should not happen until config is made
from rattail.db import Session
from rattail.db.auth import administrator_role
app = config.get_app()
model = app.model
# open db connection
model = config.get_model()
session = Session()
session = app.make_session()
# do something...for instance count the departments
# not doing anything useful here, just an example
admin = administrator_role(session)
print(admin)
# do something else...for instance count the departments
print(session.query(model.Department).count())
# must commit session to save any changes
@ -85,10 +94,8 @@ running it would look like:
.. code-block:: sh
cd /srv/envs/poser
bin/python app/foo.py --help
bin/python3 app/foo.py --help
TODO: It seems like Rattail should have a way of generating a skeleton script
like the above.
Shell Scripts
-------------