Components and Projects Scaffolding

relaxed-poetry's new command is different than the original command. While poetry's new command is used to generate a project, relaxed-poetry's new command can be used to generate any directory trees - projects, modules, build profiles and any custom component. It does so by integrating with protopy which is a directory tree templating engine.

Scaffolding using the new command

relaxed-poetry new command usage is:

Description:
  creates a directory tree based on a given template

Usage:
  rp new [options] [--] <template> [<template_args>...]

Arguments:
  template                 the template to use (supports path, git, zip, url to zip and builtins)
  template_args            template arguments, can be positional and key=value

Options:
  -o, --out                the output path to use (defaults to the active project directory, if no active project, defaults to the current directory)
  -f, --allow-override     allows the template to override existing files

...

where template descriptor is any of:

• one of rp's builtin templates (check the documentation down this section)
• name of a protopy template directory that exists inside etc/rp/templates of the current project or any of its parents.
• path to a protopy template directory
• path to a zip file containing protopy template
• a git repository descriptor: e.g., git+https://github.com/... that contains a protopy template

some templates may have arguments that can be supplied via the cli (e.g., project name, author, etc.) to see a template documentation you can append '?' (question mark) to the end of the template-descriptor like so:

> rp new project?

Description:
  Creates a new python project managed by relaxed-poetry
...

Builtin templates

Project

Description:
  Creates a new python project managed by relaxed-poetry

Usage:
  rp new project [<project_name>] [<argument=value>...]

Arguments:
  project_name        - Your project name.
  version             - Version, defaults to '0.1.0'.
  project_description - Your project description.
  readme_format       - README file type to use, can be any of: ['Markdown', 'reStructuredText'], defaults to 'Markdown'.
  author              - Author.
  license             - Your project license, defaults to 'MIT License'.
  python_version      - Required Python version classifier.
  child_project       - If executed inside a project, create a child project and update its parent, can be any of: ['true', 'false'], defaults to 'true'.

Build-Profile

Description:
  Creates a new build-profile

Usage:
  rp new build-profile [<name>] [<argument=value>...]

Arguments:
  name - Your profile name.
  type - Profile type, can be any of: ['Manual', 'Automatic'], defaults to 'Manual'.

Template

Description:
  Creates a new template

Usage:
  rp new template [<name>] [<argument=value>...]

Arguments:
  name - Your template name.

Custom templates

Custom templates are stored in etc/rp/templates inside the current project or any of its parents. To build a custom template refer to protopy-documentation, you can create an example template using rp new template command.

To use a custom template that is stored under etc/rp/templates/my-custom-template you can run:

rp new my-custom-template

ℹ️ you can override a builtin template by creating a template with the same name in etc/rp/templates.

Custom Templates - Additional Context

In addition to the methods provided to your templates by protopy, relaxd-poetry also adds the 'rp' module variable to proto.py, its intefrace is:

rp: RPContext


class RPContext:

    @property
    def active_project(self) -> Optional[PyProject]:
        """
        :return: the active project or None if rp did not got executed inside a project directory
        """

    @property
    def project_defaults(self) -> ProjectDefaults:
        """
        :return: object contains various new project defaults 
        """


class PyProject:

    def __getitem__(self, item: Union[str, List[str]]) -> Any:
        """
        :param item: table key like "tool.relaxed-poetry.properties" or ["tool", "relaxed-poetry", "properties"] 
        :return: the table if it exists otherwise None
        """

    def __setitem__(self, key: Union[str, List[str]], value: Dict):
        """
        :param key: table key like "tool.relaxed-poetry.properties" or ["tool", "relaxed-poetry", "properties"]
        :param value: a dictionary to set as the table content
        """

    def get_or_create_table(self, table_key: Union[str, List[str]]):
        """
        :param table_key: table key like "tool.relaxed-poetry.properties" or ["tool", "relaxed-poetry", "properties"] 
        :return: the existing table dictionary if it exists, otherwise, add a new table dictionary and return it
        """

    def save(self) -> None:
        """
        save the pyproject changes back to the file it was read from
        """


class ProjectDefaults:

    @property
    def author(self) -> str:
        """
        :return: the default author name 
        """

    @property
    def python_requirements(self) -> str:
        """
        :return: the default python version requirements (e.g., ^3.6) 
        """

    @property
    def buildsys_requirements(self) -> str:
        """
        :return: the default build-sys (relaxed-poetry-core) requirements (e.g., >=0.1) 
        """