# 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` and `dacreate` programs require that you have Python
installed on your computer. The `dawatchinstall` program requires
`bash` and `fswatch`. These prerequisites are easy to find on Linux
machines, but are harder to install on Windows and Mac systems. If you
run Windows, see the last section of this README for instructions on
getting a command line in Windows Subsystem for Linux.
## Installation
To install `docassemblecli` from PyPI, run:
pip install 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.
From the command line, use `cd` to navigate to the folder that
contains the `docassemble-foobar` folder. Then run:
dainstall docassemble-foobar
On Windows, you will need to write `python -m
docassemblecli.dainstall` in place of `dainstall`, so your command
will look like this:
python -m docassemblecli.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]
[--force-restart] [--server SERVER] [--playground]
[--project PROJECT] [--add] [--noconfig]
[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)
--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
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 your development installation uses more than one server, 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.
## How it works
The `dainstall` command is just a simple Python script that creates a
ZIP file and uploads it through the **docassemble** API. Feel free to
copy the code and write your own scripts to save yourself time.
## Automatically calling `dainstall`
You can use the `bash` script `dawatchinstall` to call `dainstall`
automatically every time a file in your package directory is changed.
For example, if you run:
dawatchinstall --playground --project testing docassemble-foobar
This will monitor the `docassemble-foobar` directory, and if any file
changes, it will run:
dainstall --playground --project testing --norestart docassemble-foobar
If a `.py` file is changed, however, it will run
dainstall --playground --project testing docassemble-foobar
With `dawatchinstall --playground` constantly running, then after you
save a YAML file on your local machine, it will be available for
testing on your server very quickly.
To exit `dawatchinstall`, type Ctrl-c.
To use this, both `dawatchinstall` and `dainstall` need to be in your
path; if it is not, you will need to edit the `dawatchinstall` script
so that it can successfully call the `dainstall` script.
The `dawatchinstall` script depends on the `fswatch` command. If this
command is not available on your system, you may need to install the
`fswatch` package.
## Running on Windows
If you are running Windows, a relatively convenient way to install
these command-line utilities is to use Windows Subsystem for Linux.
In the Microsoft Store, search for "Ubuntu" and install it. This may
require restarting your Windows machine. (Other Linux distributions
will work just as well, so feel free to use a different distribution
if you know what you are doing.)
Then run the Ubuntu app and answer the prompts to complete the
installation.
From the Ubuntu command line, do:
sudo apt -y update
sudo apt -y install python3-pip fswatch
sudo pip install docassemblecli
dainstall --add
The last command, `dainstall --add`, will ask for your docassemble
site URL and your API key. The API key that you supply needs to belong
to a user with `developer` or `admin` privileges.
Use `cd` to switch to the directory above where your docassemble
package is located. (Your Windows hard drive is located at `/mnt/c`
inside of Ubuntu.)
For example, assume you have a folder `docassemble-mypackage` on your
Desktop, and your username on your machine is `jsmith`. You would do:
cd /mnt/c/Users/jsmith/Desktop/
From there, you can run commands like:
dainstall docassemble-mypackage
or
dawatchinstall --playground --project mypack docassemble-mypackage
[API key]: https://docassemble.org/docs/api.html#manage_api
[docassemble]: https://docassemble.org
Raw data
{
"_id": null,
"home_page": "https://github.com/jhpyle/docassemblecli",
"name": "docassemblecli",
"maintainer": "",
"docs_url": null,
"requires_python": ">=2.7",
"maintainer_email": "",
"keywords": "",
"author": "Jonathan Pyle",
"author_email": "jhpyle@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/a3/c4/f3fb6b8e68b816bed41f7bb9de79e21de9cd0df0a976a495e1a600561d7f/docassemblecli-0.0.17.tar.gz",
"platform": null,
"description": "# docassemblecli\n\n`docassemblecli` provides command-line utilities for interacting with\n[docassemble] servers. This package is meant to be installed on your\nlocal machine, not on a [docassemble] server.\n\n## Prerequisites\n\nThe `dainstall` and `dacreate` programs require that you have Python\ninstalled on your computer. The `dawatchinstall` program requires\n`bash` and `fswatch`. These prerequisites are easy to find on Linux\nmachines, but are harder to install on Windows and Mac systems. If you\nrun Windows, see the last section of this README for instructions on\ngetting a command line in Windows Subsystem for Linux.\n\n## Installation\n\nTo install `docassemblecli` from PyPI, run:\n\n pip install docassemblecli\n\n## Usage\n\n### dacreate\n\n`docassemblecli` provides a command-line utility called `dacreate`,\nwhich creates an empty **docassemble** add-on package.\n\nTo create a package called `docassemble-foobar`, run:\n\n dacreate foobar\n\nYou will be asked some questions about the package and the\ndeveloper. This information is necessary because it goes into the\n`setup.py`, `README.md`, and `LICENSE` files of the package. If you do\nnot yet know what answers to give, just press enter, and you can edit\nthese files later.\n\nWhen the command exits, you will find a directory in the current\ndirectory called `docassemble-foobar` containing a shell of a\n**docassemble** add-on package.\n\nYou can run `dacreate --help` to get more information about how\n`dacreate` works:\n\n usage: dacreate [-h] [--developer-name DEVELOPER_NAME]\n [--developer-email DEVELOPER_EMAIL]\n [--description DESCRIPTION] [--url URL] [--license LICENSE]\n [--version VERSION] [--output OUTPUT]\n [package]\n\n positional arguments:\n package name of the package you want to create\n\n options:\n -h, --help show this help message and exit\n --developer-name DEVELOPER_NAME\n name of the developer of the package\n --developer-email DEVELOPER_EMAIL\n email of the developer of the package\n --description DESCRIPTION\n description of package\n --url URL URL of package\n --license LICENSE license of package\n --version VERSION version number of package\n --output OUTPUT output directory in which to create the package\n\n### dainstall\n\n`docassemblecli` provides a command-line utility called `dainstall`,\nwhich installs a Python package on a remote server using files on your\nlocal computer.\n\nFor example, suppose that you wrote a docassemble extension package\ncalled `docassemble.foobar` using the **docassemble** Playground. In\nthe Playground, you can download the package as a ZIP file called\n`docassemble-foobar.zip`. You can then unpack this ZIP file and you\nwill see a folder called `docassemble-foobar`. Inside of this folder\nthere is a folder called `docassemble` and a `setup.py` file.\n\nFrom the command line, use `cd` to navigate to the folder that\ncontains the `docassemble-foobar` folder. Then run:\n\n dainstall docassemble-foobar\n\nOn Windows, you will need to write `python -m\ndocassemblecli.dainstall` in place of `dainstall`, so your command\nwill look like this:\n\n python -m docassemblecli.dainstall docassemble-foobar\n\nThe first time you run this command, it will ask you for the URL of\nyour **docassemble** server and the [API key] of a user with `admin` or\n`developer` privileges.\n\nIt will look something like this:\n\n $ dainstall docassemble-foobar\n Base URL of your docassemble server (e.g., https://da.example.com): https://dev.example.com\n API key of admin user on http://localhost: H3PWMKJOIVAXL4PWUJH3HG7EKPFU5GYT\n Saved base URL and API key to .docassemblecli\n Waiting for package to install.............................\n Installed.\n\nThe next time you run `dainstall`, it will not ask you for the URL and\nAPI key.\n\nYou can run `dainstall --help` to get more information about how\n`dainstall` works:\n\n usage: dainstall [-h] [--apiurl APIURL] [--apikey APIKEY] [--norestart]\n [--force-restart] [--server SERVER] [--playground]\n [--project PROJECT] [--add] [--noconfig]\n [directory]\n\n positional arguments:\n directory\n\n options:\n -h, --help show this help message and exit\n --apiurl APIURL base url of your docassemble server, e.g.\n https://da.example.com\n --apikey APIKEY docassemble API key\n --norestart do not restart the docassemble server after installing\n package (only applicable in single-server environments)\n --force-restart unconditionally restart the docassemble server after\n installing package\n --server SERVER use a particular server from the .docassemblecli config\n file\n --playground install into your Playground instead of into the server\n --project PROJECT install into a specific project in the Playground\n --add add another server to the .docassemblecli config file\n --noconfig do not use the .docassemblecli config file\n\nFor example, you might want to pass the URL and API key in the command\nitself:\n\n dainstall --apiurl https://dev.example.com --apikey H3PWMKJOIVAXL4PWUJH3HG7EKPFU5GYT docassemble-foobar\n\nIf you have more than one server, you can run:\n\n dainstall --add\n\nto add an additional server configuration to store in your\n`.docassemblecli` config file. Then you can select the server using\n`--server`:\n\n dainstall --server dev.example.com docassemble-foobar\n\nIf you do not specify a `--server`, the first server indicated in your\n`.docassemblecli` file will be used.\n\nThe `--norestart` option can be used when your **docassemble**\ninstallation only uses one server (which is typical) and you are not\nmodifying .py files. In this case, it is not necessary for the Python\nweb application to restart after the package has been installed. This\nwill cause `dainstall` to return a few seconds faster than otherwise.\n\nThe `--force-restart` option should be used when you want to make sure\nthat **docassemble** restarts the Python web application after the\npackage is installed. By default, `dainstall` will avoid restarting\nthe server if the package has no module files and all of its\ndependencies (if any) are installed.\n\nBy default, `dainstall` installs a package on the server. If you want\nto install a package into your Playground, you can use the\n`--playground` option.\n\n dainstall --playground docassemble.foobar\n\nIf you want to install into a particular project in your Playground,\nindicate the project with `--project`.\n\n dainstall --playground --project testing docassemble-foobar\n\nInstalling into the Playground with `--playground` is faster than\ninstalling an actual Python package because it does not need to run\n`pip`.\n\nIf your development installation uses more than one server, it is safe\nto run `dainstall --playground` with `--norestart` if you are only\nchanging YAML files, because Playground YAML files are stored in cloud\nstorage and will thus be available immediately to all servers.\n\n## How it works\n\nThe `dainstall` command is just a simple Python script that creates a\nZIP file and uploads it through the **docassemble** API. Feel free to\ncopy the code and write your own scripts to save yourself time.\n\n## Automatically calling `dainstall`\n\nYou can use the `bash` script `dawatchinstall` to call `dainstall`\nautomatically every time a file in your package directory is changed.\n\nFor example, if you run:\n\n dawatchinstall --playground --project testing docassemble-foobar\n\nThis will monitor the `docassemble-foobar` directory, and if any file\nchanges, it will run:\n\n dainstall --playground --project testing --norestart docassemble-foobar\n\nIf a `.py` file is changed, however, it will run\n\n dainstall --playground --project testing docassemble-foobar\n\nWith `dawatchinstall --playground` constantly running, then after you\nsave a YAML file on your local machine, it will be available for\ntesting on your server very quickly.\n\nTo exit `dawatchinstall`, type Ctrl-c.\n\nTo use this, both `dawatchinstall` and `dainstall` need to be in your\npath; if it is not, you will need to edit the `dawatchinstall` script\nso that it can successfully call the `dainstall` script.\n\nThe `dawatchinstall` script depends on the `fswatch` command. If this\ncommand is not available on your system, you may need to install the\n`fswatch` package.\n\n## Running on Windows\n\nIf you are running Windows, a relatively convenient way to install\nthese command-line utilities is to use Windows Subsystem for Linux.\n\nIn the Microsoft Store, search for \"Ubuntu\" and install it. This may\nrequire restarting your Windows machine. (Other Linux distributions\nwill work just as well, so feel free to use a different distribution\nif you know what you are doing.)\n\nThen run the Ubuntu app and answer the prompts to complete the\ninstallation.\n\nFrom the Ubuntu command line, do:\n\n sudo apt -y update\n sudo apt -y install python3-pip fswatch\n sudo pip install docassemblecli\n dainstall --add\n\nThe last command, `dainstall --add`, will ask for your docassemble\nsite URL and your API key. The API key that you supply needs to belong\nto a user with `developer` or `admin` privileges.\n\nUse `cd` to switch to the directory above where your docassemble\npackage is located. (Your Windows hard drive is located at `/mnt/c`\ninside of Ubuntu.)\n\nFor example, assume you have a folder `docassemble-mypackage` on your\nDesktop, and your username on your machine is `jsmith`. You would do:\n\n cd /mnt/c/Users/jsmith/Desktop/\n\nFrom there, you can run commands like:\n\n dainstall docassemble-mypackage\n\nor\n\n dawatchinstall --playground --project mypack docassemble-mypackage\n\n[API key]: https://docassemble.org/docs/api.html#manage_api\n[docassemble]: https://docassemble.org\n",
"bugtrack_url": null,
"license": "",
"summary": "CLI utilities for using docassemble",
"version": "0.0.17",
"project_urls": {
"Bug Tracker": "https://github.com/jhpyle/docassemblecli/issues",
"Homepage": "https://github.com/jhpyle/docassemblecli"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a3c4f3fb6b8e68b816bed41f7bb9de79e21de9cd0df0a976a495e1a600561d7f",
"md5": "b24603a1934f6c308b063da3ac82fd2d",
"sha256": "6c0a375e08b57be2daafc58ea793151d87a9400d453f31f6710766e8ed0346ce"
},
"downloads": -1,
"filename": "docassemblecli-0.0.17.tar.gz",
"has_sig": false,
"md5_digest": "b24603a1934f6c308b063da3ac82fd2d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=2.7",
"size": 15648,
"upload_time": "2023-12-20T19:40:02",
"upload_time_iso_8601": "2023-12-20T19:40:02.696651Z",
"url": "https://files.pythonhosted.org/packages/a3/c4/f3fb6b8e68b816bed41f7bb9de79e21de9cd0df0a976a495e1a600561d7f/docassemblecli-0.0.17.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-20 19:40:02",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jhpyle",
"github_project": "docassemblecli",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "docassemblecli"
}
JSON
