docassemblecli 0.0.21

CLI utilities for using docassemble

docassemblecli

docassemblecli provides command-line utilities for interacting with docassemble servers. This package is meant to be installed on your local machine, not on a docassemble server.

Prerequisites

The dainstall, dacreate, and dadownload utility programs require that you have Python installed on your computer. If you are using MacOS or Linux, you probably have Python installed already.

Installing Python on Windows

If you are using Windows and you have not installed Python before, it is recommended that you download Python from the python.org download page rather than using the Microsoft Store. When you run the installer, there will be two checkbox options ("Use admin privileges when installing py.exe" and "Add python.exe to PATH"), and you should check both of them. Later on in the installation, you may be prompted to extend the maximum length of the PATH variable beyond 250 characters. You should click the button to make this change. Installing Python this way will make it much easier to run the utilities because you will not need to manually adjust your PATH.

Note that when you have installed Python on Windows, an application called "Python" will be available from the start menu. This application runs the Python Interpreter. The Python Interpreter is a very useful tool, but it is not the tool for installing docassemblecli or running the command line utilities dainstall, dacreate, and dadownload. To run these commands, you need to use the Windows command line application, called cmd.

Using a command line

In order to install docassemblecli and use the utilities, you will need to run an application that gives you a command line. On MacOS, you can use the Terminal application, which comes with the operating system. On Windows, you can go to the start menu and search for "cmd," which is the name of the Windows command line application.

Installation

To install docassemblecli from PyPI, run:

pip3 install docassemblecli

If you get an error, you may not have installed Python, or may not have installed it correctly. If you only have Python 2.7 installed, install the latest version of Python instead (e.g., Python 3.12 or greater.) If you know you have installed Python, but pip3 is not a recognized command, you might need to manually adjust your PATH.

To upgrade docassemblecli after you have already installed it, do:

pip3 install --upgrade docassemblecli

Usage

dacreate

docassemblecli provides a command-line utility called dacreate, which creates an empty docassemble add-on package.

To create a package called docassemble-foobar, run:

dacreate foobar

You will be asked some questions about the package and the developer. This information is necessary because it goes into the setup.py, README.md, and LICENSE files of the package. If you do not yet know what answers to give, just press enter, and you can edit these files later.

When the command exits, you will find a directory in the current directory called docassemble-foobar containing a shell of a docassemble add-on package.

You can run dacreate --help to get more information about how dacreate works:

usage: dacreate [-h] [--developer-name DEVELOPER_NAME]
                [--developer-email DEVELOPER_EMAIL]
                [--description DESCRIPTION] [--url URL] [--license LICENSE]
                [--version VERSION] [--output OUTPUT]
                [package]

positional arguments:
  package               name of the package you want to create

options:
  -h, --help            show this help message and exit
  --developer-name DEVELOPER_NAME
                        name of the developer of the package
  --developer-email DEVELOPER_EMAIL
                        email of the developer of the package
  --description DESCRIPTION
                        description of package
  --url URL             URL of package
  --license LICENSE     license of package
  --version VERSION     version number of package
  --output OUTPUT       output directory in which to create the package

dainstall

docassemblecli provides a command-line utility called dainstall, which installs a Python package on a remote server using files on your local computer.

For example, suppose that you wrote a docassemble extension package called docassemble.foobar using the docassemble Playground. In the Playground, you can download the package as a ZIP file called docassemble-foobar.zip. You can then unpack this ZIP file and you will see a folder called docassemble-foobar. Inside of this folder there is a folder called docassemble and a setup.py file. Your interview YAML files will be in the folder docassemble/foobar/data/questions. Your templates will be in the folder docassemble/foobar/data/templates. Your modules will be in the folder docassemble/foobar. Now you can use your favorite text editor to edit your .yml and .py files, and you can use dainstall to install the package on your server so that you can test your changes.

From the command line, use cd to navigate to the folder that contains the docassemble-foobar folder. Then run:

dainstall docassemble-foobar

The first time you run this command, it will ask you for the URL of your docassemble server and the API key of a user with admin or developer privileges.

It will look something like this:

$ dainstall docassemble-foobar
Base URL of your docassemble server (e.g., https://da.example.com): https://dev.example.com
API key of admin user on http://localhost: H3PWMKJOIVAXL4PWUJH3HG7EKPFU5GYT
Saved base URL and API key to .docassemblecli
Waiting for package to install.............................
Installed.

The next time you run dainstall, it will not ask you for the URL and API key.

You can run dainstall --help to get more information about how dainstall works:

usage: dainstall [-h] [--apiurl APIURL] [--apikey APIKEY] [--norestart]
                 [--watch] [--force-restart] [--server SERVER] [--playground]
                 [--project PROJECT] [--add] [--noconfig] [--debug]
                 [directory]

positional arguments:
  directory

options:
  -h, --help         show this help message and exit
  --apiurl APIURL    base url of your docassemble server, e.g.
                     https://da.example.com
  --apikey APIKEY    docassemble API key
  --norestart        do not restart the docassemble server after installing
                     package (only applicable in single-server environments)
  --watch            watch the directory for changes and install changes when
                     there is a change
  --force-restart    unconditionally restart the docassemble server after
                     installing package
  --server SERVER    use a particular server from the .docassemblecli config
                     file
  --playground       install into your Playground instead of into the server
  --project PROJECT  install into a specific project in the Playground
  --add              add another server to the .docassemblecli config file
  --noconfig         do not use the .docassemblecli config file
  --debug            use verbose logging

For example, you might want to pass the URL and API key in the command itself:

dainstall --apiurl https://dev.example.com --apikey H3PWMKJOIVAXL4PWUJH3HG7EKPFU5GYT docassemble-foobar

If you have more than one server, you can run:

dainstall --add

to add an additional server configuration to store in your .docassemblecli config file. Then you can select the server using --server:

dainstall --server dev.example.com docassemble-foobar

If you do not specify a --server, the first server indicated in your .docassemblecli file will be used.

The --norestart option can be used when your docassemble installation only uses one server (which is typical) and you are not modifying .py files. In this case, it is not necessary for the Python web application to restart after the package has been installed. This will cause dainstall to return a few seconds faster than otherwise.

The --force-restart option should be used when you want to make sure that docassemble restarts the Python web application after the package is installed. By default, dainstall will avoid restarting the server if the package has no module files and all of its dependencies (if any) are installed.

By default, dainstall installs a package on the server. If you want to install a package into your Playground, you can use the --playground option.

dainstall --playground docassemble.foobar

If you want to install into a particular project in your Playground, indicate the project with --project.

dainstall --playground --project testing docassemble-foobar

Installing into the Playground with --playground is faster than installing an actual Python package because it does not need to run pip.

If you are using a multi-server configuration, it is safe to run dainstall --playground with --norestart if you are only changing YAML files, because Playground YAML files are stored in cloud storage and will thus be available immediately to all servers.

You can run dainstall with the --watch option if you want your package to be automatically updated on the server every time a file in your package directory is changed.

For example, suppose you run:

dainstall --watch --playground --project testing docassemble-foobar

This will monitor the docassemble-foobar directory, and if any file within the directory is modified, or a new file is created, the package will be reinstalled into the testing project of the Playground belonging to the owner of the API key.

To exit, type Ctrl-c.

The --watch feature tries to be as efficient as possible. If you modify a file in the data folder, it will not restart the server afterward. However, it will restart the server if you modify a .py file, because otherwise you would not be able to see the effect of the change. If you are using --playground, the dainstall --watch feature will only upload the specific file or files that you modified, rather than uploading the whole package.

Thus, for the fastest development experience, use --watch and --playground.

If you encounter problems, try running dainstall with the --debug option.

dadownload

The dadownload utility downloads a package from a docassemble server and saves it to the current working directory. It connects to a docassemble server in the same way that dainstall does.

usage: dadownload [-h] [--overwrite] [--apiurl APIURL] [--apikey APIKEY]
                  [--server SERVER] [--playground] [--project PROJECT] [--add]
                  [--noconfig]
                  [package]

positional arguments:
  package

options:
  -h, --help         show this help message and exit
  --overwrite        overwrite existing files
  --apiurl APIURL    base url of your docassemble server, e.g.
                     https://da.example.com
  --apikey APIKEY    docassemble API key
  --server SERVER    use a particular server from the .docassemblecli config
                     file
  --playground       download from the Playground
  --project PROJECT  download from a specific project in the Playground
  --add              add another server to the .docassemblecli config file
  --noconfig         do not use the .docassemblecli config file

For example, if you run dadownload docassemble.foo (or dadownload foo, which will do the same thing), a directory docassemble-foo will be created, containing the docassemble.foo package that is installed on the docassemble server.

If you use --playground, then the files specified in a package in the Packages folder of the Playground will be collected and downloaded to the current working directory.

Without --playground, the package that is installed on the server will be downloaded to the current working directory. This only works if the package was installed by uploading a ZIP file. (Note that the dainstall command installs packages by uploading a ZIP file.) If the package you want to download is on GitHub, use git clone to obtain it. If the package is only on PyPI, use pip download to download the code.

By default, dadownload will not overwrite any existing files. You can override this by specifying --overwrite.

Text editors that create hidden and temporary files

Text editors often create hidden files and hidden directories in your project folder for their own purposes, such as backup files and files that facilitate linting. This can be problematic when you are using git, because you do not want these temporary files to appear on GitHub. These files may cause dainstall --watch to think that a file in your project has been modified, when it actually has not.

The dainstall command tries to avoid this. If you have git installed, dainstall will call git ls-files to see what your .gitignore file is screening out, and then tries to avoid these files. It also uses regular expressions to avoid certain files and directories.

If your development environment triggers dainstall --watch too much, submit a GitHub issue in the jhpyle/docassemblecli repository explaining the situation. It may be possible to tweak the code to avoid the unnecessary triggering.