Project Setup

You can set up a TorchApp project automatically using the built in cookiecutter template or you can add it manually to an existing Python package.

Automatic Generation

To generate a project using torchapp, then run the command-line utility.

torchapp

This uses https://cookiecutter.readthedocs.io/ cookiecutter to generate a project for you.

This will use the template that comes with your torchapp installation. If you wish to use the most up-to-date template, then run

torchapp gh

This will use the template from the torchapp-cookiecutter repository on Github. If you wish to create your own template, feel free to fork that repository and use the new URL as the command-line argument.

The dependency management is handeled using poetry. Install poetry using the instructions here: https://python-poetry.org/docs/#installation Then to install the dependencies, run:

poetry install

Enter the virtual environment with:

poetry setup

The command-line utility should be installed to your path automatically in that environment.

Automatic Generation Reference

torchapp

Generate a torchapp project using Cookiecutter (https://github.com/audreyr/cookiecutter)

torchapp [OPTIONS]

Options

--template <template>

The Cookiecutter template to use. If left blank then it uses the default template in this version of torchapp. If ‘gh’ or ‘github’ then it uses the latest torchapp cookiecutter template at https://github.com/rbturnbull/torchapp-cookiecutter

Default

--checkout <checkout>: A branch, tag or commit to checkout after git clone

--no-input, --no-no-input

Do not prompt for parameters and only use cookiecutter.json file content

Default: False

--extra-context <extra_context>

--replay, --no-replay

Do not prompt for parameters and only use information entered previously

Default: False

--overwrite-if-exists, --no-overwrite-if-exists

Overwrite the contents of the output directory if it already exists

Default: False

--output-dir <output_dir>

Where to output the generated project dir into

Default: .

--config-file <config_file>: User configuration file

--default-config, --no-default-config

Do not load a config file. Use the defaults instead

Default: False

--directory <directory>: Directory within repo that holds cookiecutter.json file for advanced repositories with multi templates in it

--skip-if-file-exists, --no-skip-if-file-exists

Skip the files in the corresponding directories if they already exist

Default: False

--install-completion <install_completion>

Install completion for the specified shell.

Options: bash | zsh | fish | powershell | pwsh

--show-completion <show_completion>

Show completion for the specified shell, to copy it or customize the installation.

Options: bash | zsh | fish | powershell | pwsh

Manual Setup

You can use TorchApp in an existing project, by following these steps.

If you are using the poetry dependency management system, the install the app like this:

poetry add git+https://github.com/rbturnbull/torchapp.git#main

If using pip then:

pip install git+https://github.com/rbturnbull/torchapp.git#main

Then in your code (perhaps in a file named apps.py) subclass TorchApp and implement at least the dataloaders and the model methods.

import torchapp as ta

class MyApp(ta.TorchApp):
    def dataloaders(self):
        ...

    def model(self):
        ...

If you are using a file as the main script then instantiate the app and call the main function:

if __name__ == "__main__":
    MyApp().main()

If you wish to include the app in a python package, it is easiest to use the poetry dependency management system. In the pyproject.toml file add the main method of your app to the scripts section like this:

[tool.poetry.scripts]
executable = "path.to.script:MyApp.main"

For example, if the name of the executable was going to be logistic and the path to the file from the base directory was logistic/apps.py and the subclass of TorchApp was called LogisticApp, then the following would be added to pyproject.toml:

[tool.poetry.scripts]
logistic = "logistic.apps:LogisticApp.main"

Pre-commit Hooks

To set up black code formatting with a pre-commit hook, run:

pre-commit install

Coverage Badge

To set up the automatic coverage badge on Github, you need to create a Github authorization token (https://github.com/settings/tokens/new) and give it permission to modify gists. Then add this token as the secret in Settings/Secrets/Actions with the variable name: GIST_SECRET.