Metadata-Version: 2.4
Name: pyprj
Version: 0.12.0
Summary: An opinionated CLI tool to manage python projects.
Author: Diogo Rossi
Author-email: Diogo Rossi <rossi.diogo@gmail.com>
License-Expression: MIT
Classifier: Programming Language :: Python :: 3.12
Requires-Dist: clig>=0.7.0
Requires-Dist: taskipy>=1.14.1
Requires-Dist: ipython>=9.10.0 ; extra == 'ipython'
Requires-Python: >=3.12
Project-URL: Documentation, https://github.com/diogo-rossi/pyprj/blob/main/README.md
Project-URL: Issues, https://github.com/diogo-rossi/pyprj/issues
Project-URL: Source, https://github.com/diogo-rossi/pyprj/
Provides-Extra: ipython
Description-Content-Type: text/markdown

# PyPrj

[![PyPI - Version](https://img.shields.io/pypi/v/pyprj.svg)](https://pypi.org/project/pyprj)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/pyprj.svg)](https://pypi.org/project/pyprj)

An opinionated CLI tool to manage python projects.

Makes use of:

- [VS Code](https://code.visualstudio.com/) as IDE.
- [uv](https://docs.astral.sh/uv/) as package manager.
- [pytest](https://docs.pytest.org/en/stable/#) as testing framework.
- [black](https://black.readthedocs.io/en/stable/#) to format python files.
- [Prettier](https://prettier.io/) to format markdown files.
- [Sphinx](https://www.sphinx-doc.org/en/master/#) framework to write
  documentation.
- [MyST](https://myst-parser.readthedocs.io/en/latest/#) parser extension to
  write sphinx docs with markdown.
- [Furo](https://github.com/pradyunsg/furo?tab=readme-ov-file#furo) as sphinx
  theme.
- [Jupyter](https://jupyter.org/) to write jupyter notebooks that are converted
  into markdown.
- [taskipy](https://pypi.org/project/taskipy/) to run automated tasks.
- [Read the Docs](https://about.readthedocs.com/) as pre-set option to host
  documentation.
- [MIT](https://opensource.org/license/mit) as license.
- [clig](https://pypi.org/project/clig/) library for CLI projects.

## Installation

A good way to install CLI tools made with python is using
[`pipx`](https://pipx.pypa.io/stable/).

```sh
pipx install pyprj
```

With `pipx`, the tool is globally installed in an isolated environment.

## Usage

Look at the help messages from the CLI (using `--help`). Some of the messages
are bellow.

### Main command

```none
> pyprj --help

usage: pyprj [-h] [-v] {init,test,docs,upver,build,publish} ...

A CLI to manage python projects with predefined tools.

options:
  -h, --help            Show this help message and exit.
  -v, --version         show program's version number and exit

subcommands:
  {init,test,docs,upver,build,publish}
    init                Create a new project for a python package.
    test                Run task `test` inside the project.
    docs                Manage documentation of the project.
    upver               Update or show project version.
    build               Run task `build` inside the project.
    publish             Publish package to PyPI.
```

### `init` subcommand

```none
> pyprj init --help

usage: pyprj init [-h] [-n <name>] [-p <python-version>] [-b <black-line-length>] [-c [<cli-name>]] [-N]

Create a new project for a python package.

options:
  -h, --help            Show this help message and exit.

  -n <name>, --name <name>
                        The name of the project. If `None`, use the current directory's
                        name.
                        Defaults to 'None'.

  -p <python-version>, --python-version <python-version>
                        The Python interpreter version to use to determine the minimum
                        supported Python version.
                        Defaults to '3.12'.

  -b <black-line-length>, --black-line-length <black-line-length>
                        Line length parameter to use with `black`.
                        Defaults to '128'.

  -c [<cli-name>], --cli [<cli-name>]
                        Optional CLI script name. If omitted, No CLI command is added.
                        If provided without a value, the CLI command name defaults to the
                        name of the package.

  -N, --no-about        Whether to not add an `__about__.py` file in the project's `src`
                        folder with the `__version__` property. The default (`False`) will
                        add the file.
                        Defaults to 'False'.
```

### `test` subcommand

```none
> pyprj test --help

usage: pyprj test [-h]

Run task `test` inside the project.

This command only runs the task `test` inside the project.
Tasks use the tool `taskipy`. Currently are run with the tool `uv`.
The task `test` runs tests with `pytest` in folder `./tests`.

options:
  -h, --help  Show this help message and exit.
```

### `docs` subcommand

```none
> pyprj docs --help

usage: pyprj docs [-h] {init,nbex,nbmd,modm} ...

Manage documentation of the project.

If called without subcommands, runs the task `docs` inside the project.
Tasks use the tool `taskipy`. Currently are run with the tool `uv`.
The task `docs` makes docs with `sphinx` in folder `./doc/sphinx`.

options:
  -h, --help            Show this help message and exit.

subcommands:
  {init,nbex,nbmd,modm}
    init                Initialize documentation folder with packages.
    nbex                Process jupyter (nb) files to generate example files of code.
    nbmd                Process jupyter (nb) files to generate markdown (md) files.
    modm                Process documentation in modules.
```

#### `docs/init` subcommand

```none
> pyprj docs init --help

usage: pyprj docs init [-h] [-a]

Initialize documentation folder with packages.

options:
  -h, --help       Show this help message and exit.

  -a, --add-pyprj  Whether to add `pyprj` itself in the `docs` dependency group of
                   the project.
                   Defaults to 'False'.
```

#### `docs/nbmd` subcommand

```none
> pyprj docs nbmd --help

usage: pyprj docs nbmd [-h] [-k {tutorial,function,class}] [-n] [-r <pattern>] [-d] [filepath ...]

Process jupyter (nb) files to generate markdown (md) files.

positional arguments:
  filepath              The filepath or filepaths of jupyter notebook (`.ipynb`) to convert
                        to markdown. If `None` (default), process all notebook files from
                        the current directory.

options:
  -h, --help            Show this help message and exit.

  -k {tutorial,function,class}, --kind {tutorial,function,class}
                        The kind of the notebook files documentation to convert.
                        Defaults to 'tutorial'.

  -n, --no-prettier     Whether to not pos-process the generate .md files with `prettier`,
                        if `prettier` is available.
                        Defaults to 'False'.

  -r <pattern>, --remove-pattern-shell-files <pattern>
                        Pattern to remove in shell command line cells. Aiming to remove
                        example command line folders from path.
                        Defaults to 'examples/'.

  -d, --dont-run-notebooks-before
                        Whether to not run the jupyter notebooks before processing.
                        Defaults to 'False'.
```

#### `docs/nbex` subcommand

```none
> pyprj docs nbex --help

usage: pyprj docs nbex [-h] [-o] [-n] [-d <dest-directory>] [-O <output-suffix>] [filepath ...]

Process jupyter (nb) files to generate example files of code.
Create files from the cells starting with `%%`.

positional arguments:
  filepath              The filepath or filepaths of jupyter notebook (`.ipynb`) to
                        generate examples. If `None` (default), process all notebook
                        files from the current directory.

options:
  -h, --help            Show this help message and exit.

  -o, --only-rename-examples
                        Whether to only rename the example cells, not generating example
                        files.
                        Defaults to 'False'.

  -n, --no-change-shell-cells
                        Whether to not edit the following shell cells, after the example
                        cells.
                        Defaults to 'False'.

  -d <dest-directory>, --dest-directory <dest-directory>
                        Directory of the resulting examples files.
                        Defaults to 'examples'.

  -O <output-suffix>, --output-suffix <output-suffix>
                        If editing original notebook file (`change_shell_cells=True`) add
                        this suffix to the resulting file. Used for debbuging purposes, to
                        not overwrite the original file (which is done with the default
                        value).
                        Defaults to ''.
```

#### `docs/modm` subcommand

```none
> pyprj docs modm --help

usage: pyprj docs modm [-h] [filepath ...]

Process documentation in modules.

positional arguments:
  filepath    The filepath or filepaths of modules (.py) to process.
              If `None` (default), process all python files from the current directory.

options:
  -h, --help  Show this help message and exit.
```

### `build` subcommand

```none
> pyprj build --help

usage: pyprj build [-h]

Run task `build` inside the project.

This command only runs the task `build` inside the project.
Tasks use the tool `taskipy`. Currently are run with the tool `uv`.
The task `build` builds the package with `uv` in root folder.

options:
  -h, --help  Show this help message and exit.
```

### `upver` subcommand

```none
> pyprj upver --help

usage: pyprj upver [-h] [-b] [{major,minor,patch}]

Update or show project version.

positional arguments:
  {major,minor,patch}  Semantic version pattern of the updated version.

options:
  -h, --help           Show this help message and exit.

  -b, --build          Whether to build the project after update version.
                       Defaults to 'False'.


Currently, it uses the command `uv version`.
If called without positional arguments, only show the project version.
```

### `publish` subcommand

```none
> pyprj publish --help

usage: pyprj publish [-h]

Publish package to PyPI.

Uses token from file `.vscode/pyprj.json`.

options:
  -h, --help  Show this help message and exit.
```
## License

`pyprj` is distributed under the terms of the
[MIT](https://spdx.org/licenses/MIT.html) license.
