pymetacode.coding module

The actual code generators of the pymetacode package.

Currently, there are the following types of code generators:

Each of these generators uses templates in the templates subdirectory of the pymetacode package.

class pymetacode.coding.PackageCreator

Bases: object

Generate the basic package structure.

The basic package structure follows Python best practices and has been used in a number of packages by the author of this package. In short, the modules reside in a subdirectory with the same name as the package, and parallel to that are directories for tests and documentation (“tests”, “docs”).

Furthermore, a “setup.py” file is created to have the package installable using pip, and a license (“LICENSE”) and readme (“README.rst”) file are present.

The package version is stored in the file “VERSION”, a “.gitignore” file exists as well in the package root, and depending on the configuration, a git repository is initialised within the package root directory. In this case, a pre-commit hook is installed as well incrementing the version number for each commit, using the file “incrementVersion.sh” from the “bin” directory, and auto-formatting Python code using Black on each commit.

In case of the gui option in the configuration being set, a scaffold for a complete GUI (based on Qt6, PySide6) is added. See the GuiCreator class for further details.

name

Name of the package to be created.

Will usually be read from the configuration.

Type

str

subdirectories

Directories and subdirectories created within the package root.

Type

list

configuration

Configuration as usually read from the configuration file.

Type

pymetacode.configuration.Configuration

documentation

Settings for creating the documentation.

Type

dict

Examples

The following examples demonstrate how to use the CLI from the terminal, rather than how to use this class programmatically.

The first step when creating a new package is to write a config file that can be filled with sensible content afterwards:

pymeta write config to mypackage_config.yaml

This would write the default configuration to “mypackage_config.yaml”. Change all values in this file according to your needs. Afterwards, you can create the basic structure of your new project:

pymeta create package from mypackage_config.yaml

Now, you have a complete package that is installable and deployable.

create(name='')

Generate the basic package structure.

Parameters

name (str) –

Name of the package to create.

If provided, this will set the name attribute of the class.

class pymetacode.coding.ModuleCreator

Bases: object

Add a module to an existing package.

Actually, adding a module consists of creating three files: the module itself, an accompanying test module, and the API documentation file. The latter gets added to the API toctree directive as well.

If you try to add an already existing module, a warning is raised and no further action taken, in order not to overwrite existing code.

If the module name contains a dot, the first part will be interpreted as subpackage and the second as module name. In this case, the module is added to the subpackage, and the API documentation handled accordingly.

If you try to add a module to a nonexisting subpackage, a warning is raised and no further action taken. In such case, first create the subpackage. See the SubpackageCreator class for further details.

name

Name of the module to be created.

Type

str

subpackage

Name of the subpackage (if any).

If the name of a module contains a dot, the part before the dot is interpreted as subpackage.

If the subpackage does not exist, a warning is issued and no module created.

New in version 0.5.

Type

str

configuration

Configuration as usually read from the configuration file.

Type

pymetacode.configuration.Configuration

Raises

ValueError – Raised if no name is provided

Examples

The following examples demonstrate how to use the CLI from the terminal, rather than how to use this class programmatically.

Prerequisite for using the CLI is to have the package configuration stored within the package root directory in the file “.project_configuration.yaml”. This will be the case if the package has been created by the CLI as well. Furthermore, all following commands need to be issued from within the root directory of your package.

pymeta add module mymodule

This will add a module “mymodule” to your package, together with a “test_mymodule” module in the “tests” subdirectory. And even better, the API documentation will be updated as well for you.

Suppose you would have a subpackage “mysubpackage” and would want to add a module to this subpackage. In this case, simply use the familiar dot notation for separating subpackage and module:

pymeta add module mysubpackage.mymodule

This will add a module “mymodule” to the subpackage “mysubpackage” of your package, together with a “test_mymodule” module in the “mysubpackage” subdirectory of the “tests” directory. And even better, the API documentation will be updated for you as well.

This can even be cascaded and used for nested subpackages:

pymeta add module mysubpackage.mysubsubpackage.mymodule

This will add a module “mymodule” to the subpackage “mysubsubpackage” of the subpackage “mysubpackage” of your package, together with a “test_mymodule” module in the “mysubpackage/mysubsubpackage” subdirectory of the “tests” directory. And even better, the API documentation will be updated for you as well.

Changed in version 0.6: Support for nested subpackages

create(name='')

Add a module to an existing package.

Parameters

name (str) –

Name of the module to add.

If provided, this will set the name attribute of the class.

class pymetacode.coding.ClassCreator

Bases: object

Add a class to an existing module, including a test class.

When a class is added to a module, it will always be added to the bottom of the module file, and at the same time a test class with a very basic setup and a first test will be added to the corresponding test module.

If you try to add an already existing class to the given module, a warning is raised and no further action taken, in order not to overwrite existing code.

name

Name of the class to be added to the module

Type

str

module

Name of the module the class should be added to

Type

str

subpackage

Name of the subpackage (if any).

If the name of a module contains a dot, the part before the dot is interpreted as subpackage.

If the subpackage does not exist, an exception is raised.

New in version 0.5.

Type

str

configuration

Configuration as usually read from the configuration file.

Type

pymetacode.configuration.Configuration

Raises

ValueError – Raised if no class or module name is provided

Examples

The following examples demonstrate how to use the CLI from the terminal, rather than how to use this class programmatically.

Prerequisite for using the CLI is to have the package configuration stored within the package root directory in the file “.project_configuration.yaml”. This will be the case if the package has been created by the CLI as well. Furthermore, all following commands need to be issued from within the root directory of your package.

pymeta add class MyClass to mymodule

This will add the class “MyClass” to the module “mymodule”, together with a test class in the “test_mymodule” module. The class will come with a basic docstring, and the test class with a minimalistic setup and first test (for implementation of the class) that gets you started with writing further tests.

Suppose you have a subpackage “mysubpackage” and would want to add a class to a module of this subpackage. In this case, simply use the familiar dot notation for separating subpackage and module:

pymeta add class MyClass to mysubpackage.mymodule

This will add the class “MyClass” to the module “mymodule” in the subpackage “mysubpackage”, together with a test class in the “test_mymodule” module in the respective “mysubpackage” directory. The class will come with a basic docstring, and the test class with a minimalistic setup and first test (for implementation of the class) that gets you started with writing further tests.

This can even be cascaded and used for nested subpackages:

pymeta add class MyClass to mysubpackage.mysubsubpackage.mymodule

This will add the class “MyClass” to the module “mymodule” in the subpackage “mysubsubpackage” in the subpackage “mysubpackage”, together with a test class in the “test_mymodule” module in the respective “mysubpackage/mysubsubpackage” directory. The class will come with a basic docstring, and the test class with a minimalistic setup and first test (for implementation of the class) that gets you started with writing further tests.

Changed in version 0.6: Support for nested subpackages

create(name='', module='')

Create actual code stub for the class.

Parameters

  • name (str) – Name of the function to be created

  • module (str) – Name of the module the function should be added to

Raises

ValueError – Raised if function or module name is missing

class pymetacode.coding.FunctionCreator

Bases: object

Add a function to an existing module, including a test class.

When a function is added to a module, it will always be added to the bottom of the module file, and at the same time a test class with a first test will be added to the corresponding test module.

If you try to add an already existing function to the respective module, a warning is raised and no further action taken, in order not to overwrite existing code.

name

Name of the function to be added to the module

Type

str

module

Name of the module the function should be added to

Type

str

subpackage

Name of the subpackage (if any).

If the name of a module contains a dot, the part before the dot is interpreted as subpackage.

If the subpackage does not exist, an exception is raised.

New in version 0.5.

Type

str

configuration

Configuration as usually read from the configuration file.

Type

pymetacode.configuration.Configuration

Raises

ValueError – Raised if no function or module name is provided

Examples

The following examples demonstrate how to use the CLI from the terminal, rather than how to use this class programmatically.

Prerequisite for using the CLI is to have the package configuration stored within the package root directory in the file “.project_configuration.yaml”. This will be the case if the package has been created by the CLI as well. Furthermore, all following commands need to be issued from within the root directory of your package.

pymeta add function my_function to mymodule

This will add the function “my_function” to the module “mymodule”, together with a test class in the “test_mymodule” module. The function will come with a basic docstring, and the test class with a minimalistic first test that gets you started with writing further tests.

Suppose you have a subpackage “mysubpackage” and would want to add a function to a module of this subpackage. In this case, simply use the familiar dot notation for separating subpackage and module:

pymeta add function my_function to mysubpackage.mymodule

This will add the function “my_function” to the module “mymodule” in the subpackage “mysubpackage”, together with a test class in the “test_mymodule” module in the respective “mysubpackage” directory. The function will come with a basic docstring, and the test class with a minimalistic setup and first test that gets you started with writing further tests.

This can even be cascaded and used for nested subpackages:

pymeta add function my_function to mysubpackage.mysubsubpackage.mymodule

This will add the function “my_function” to the module “mymodule” in the subpackage “mysubsubpackage” in the subpackage “mysubpackage”, together with a test class in the “test_mymodule” module in the respective “mysubpackage/mysubsubpackage” directory. The function will come with a basic docstring, and the test class with a minimalistic setup and first test that gets you started with writing further tests.

Changed in version 0.6: Support for nested subpackages

create(name='', module='')

Create actual code stub for the function.

Parameters

  • name (str) – Name of the function to be created

  • module (str) – Name of the module the function should be added to

Raises

ValueError – Raised if function or module name is missing

class pymetacode.coding.GuiCreator

Bases: object

Add PySide6-based (Qt6) GUI subpackage to an existing package.

If you want to add a GUI to your package, this involves extending the overall package structure with a GUI submodule (as well in the tests). For now, the pymetacode package only supports creating GUIs using Qt6 and the PySide6 bindings. The package structure of the added subpackages follows best practices. An example of the additional package structure is shown below.

In case a GUI already exists (or at least the gui subpackage), a warning is raised and no further action taken, in order not to overwrite existing code.

mypackage
├── docs
│   ├── api
│   │   ├── gui
│   │   │   ├── mypackage.gui.app.rst
│   │   │   ├── mypackage.gui.mainwindow.rst
│   │   │   └── index.rst
│   │   └── ...
│   └── ...
├── mypackage
│   ├── gui
│   │   ├── app.py
│   │   ├── data
│   │   │   ├── icon.svg
│   │   │   └── splash.svg
│   │   ├── __init__.py
│   │   ├── mainwindow.py
│   │   ├── Makefile
│   │   └── ui
│   │       └── __init__.py
│   └── ...
└── tests
    ├── gui
    │   ├── __init__.py
    │   └── test_mainwindow.py
    └── ...

To summarise, what is added in terms of subdirectories:

  1. A gui directory within the package source directory

  2. A gui directory within the package tests directory

  3. A gui directory within the package API docs directory

The gui directories in source and tests as well as the gui.ui directory behave like subpackages, as they all contain an __init__.py file.

The gui directory in the package source directory deserves a few more comments:

  • The user interface (*.ui) files containing the XML description of the Qt windows created by/modified with the Qt Designer reside in the ui subdirectory, together with the auto-generated Python files used for import. To help with auto-generating the Python files from the ui files, use the Makefile in the gui subdirectory.

  • Additional data files, such as icons or images for a splash screen, reside in the data subdirectory.

  • The app.py module contains the main entrance point to the GUI that is added to the gui_scripts entrypoint in the setup.py file.

  • The mainwindow.py module contains all relevant code for the main GUI window.

    pymetacode uses the qtbricks package, hence the definition of the main window is rather minimal to start with and does not use ui files/the Qt Designer. Have a look at qtbricks.mainwindow for details.

  • The Makefile is used for convenience to generate the Python files from the ui files used by the Qt Designer. Simply type make in the gui subdirectory to have them built.

If you would like to add additional windows to your existing GUI, have a look at the GuiWindowCreator class.

configuration

Configuration as usually read from the configuration file.

Type

pymetacode.configuration.Configuration

subdirectories

Subdirectories created within the package source directory.

Type

list

Examples

The following example demonstrates how to use the CLI from the terminal, rather than how to use this class programmatically, as this is the preferred and intended use case.

Prerequisite for using the CLI is to have the package configuration stored within the package root directory in the file “.project_configuration.yaml”. This will be the case if the package has been created by the CLI as well. Furthermore, all following CLI commands need to be issued from within the root directory of your package.

pymeta add gui

This will add the basic structure for a GUI to your package, including tests and documentation.

However, in case you want or need to access pymetacode programmatically, this is the series of steps you would need to perform to create a GUI. At the same time, this is a minimum scenario for manually testing the functionality:

from pymetacode import coding, configuration, utils

cfg = configuration.Configuration()
cfg.package['name'] = 'pkgname'

pkg = coding.PackageCreator()
pkg.configuration = cfg
pkg.create(name=cfg.package['name'])

with utils.change_working_dir(cfg.package['name']):
    gui = coding.GuiCreator()
    gui.configuration = cfg
    gui.create()

As you see here, this assumes no package to preexist. The crucial step is to create a configuration first and as a bare minimum set the package name. Next comes creating the package, and only afterwards the GUI. The configuration is reused in both cases.

New in version 0.4.

create()

Create actual code stub for the GUI subpackage.

This will create a number of files and (sub)directories, as mentioned in the GuiCreator class documentation.

class pymetacode.coding.GuiWindowCreator

Bases: object

Add a PySide6-based (Qt6) GUI window to an existing GUI subpackage.

Actually, adding a GUI window consists of creating a number of files:

  1. the module used to call the GUI window

  2. the corresponding ui file defining the Qt layout of the window

  3. an accompanying test module

  4. the API documentation file

The latter gets added to the API toctree directive as well.

If you try to add an already existing GUI window, a warning is raised and no further action taken, in order not to overwrite existing code.

configuration

Configuration as usually read from the configuration file.

Type

pymetacode.configuration.Configuration

Raises

ValueError – Raised if no name is provided

Examples

The following example demonstrates how to use the CLI from the terminal, rather than how to use this class programmatically, as this is the preferred and intended use case.

Prerequisite for using the CLI is to have the package configuration stored within the package root directory in the file “.project_configuration.yaml”. This will be the case if the package has been created by the CLI as well. Furthermore, all following CLI commands need to be issued from within the root directory of your package.

pymeta add window mywindow

This will add the GUI window mywindow to the gui subpackage of your package, together with the test_mywindow module in the tests.gui directory. Furthermore, the corresponding UI file (to be used with the Qt Designer) gets added to the gui/ui subpackage. And even better, the API documentation will be updated as well for you.

New in version 0.4.

property name

Name of the GUI window to be created.

A suffix “window” gets added if not present, and the name is ensured to be in lowercase letters.

Returns

name – Name of the GUI window to be created.

Return type

str

property class_name

The name of the class containing the GUI window.

Similar to name, but in CamelCase with the first letter capitalised and the suffix “Window”.

Returns

class_name – The name of the class containing the GUI window.

Return type

str

create(name='')

Create actual code stub for the GUI window.

This will create a number of files:

  1. the module used to call the GUI window

  2. the corresponding ui file defining the Qt layout of the window

  3. an accompanying test module

  4. the API documentation file

The latter gets added to the API toctree directive as well.

class pymetacode.coding.SubpackageCreator

Bases: object

Add a subpackage to an existing package.

Actually, adding a subpackage consists of creating three directories and three files: the subpackage itself, an accompanying test subpackage, and the API documentation subdirectory. The latter gets added to the API toctree directive as well. Furthermore, in the subpackage and test subpackage directories __init__.py files are created, and an index file for the subpackage API documentation.

If you try to add an already existing subpackage, a warning is raised and no further action taken, in order not to overwrite existing code.

name

Name of the subpackage to be created.

Type

str

configuration

Configuration as usually read from the configuration file.

Type

pymetacode.configuration.Configuration

Raises

ValueError – Raised if no name is provided

Examples

The following examples demonstrate how to use the CLI from the terminal, rather than how to use this class programmatically.

Prerequisite for using the CLI is to have the package configuration stored within the package root directory in the file “.project_configuration.yaml”. This will be the case if the package has been created by the CLI as well. Furthermore, all following commands need to be issued from within the root directory of your package.

pymeta add subpackage mysubpackage

This will add a subpackage “mysubpackage” to your package, together with a “mysubpackage” subpackage in the “tests” subdirectory. And even better, the API documentation will be updated for you as well.

This can even be cascaded and used for nested subpackages. In this case, simply use the familiar dot notation for separating subpackages:

pymeta add subpackage mysubpackage.mysubsubpackage

This will add a subpackage “mysubsubpackage” to the subpackage “mysubpackage” in your package, together with a “mysubpackage/mysubsubpackage” subpackage in the “tests” subdirectory. And even better, the API documentation will be updated for you as well.

Note

If you like to create nested subpackages as described above, make sure to sequentially create all intermediate subpackages. Otherwise, you subpackage will not be created and a warning issued.

New in version 0.5.

Changed in version 0.6: Support for nested subpackages

create(name='')

Add a subpackage to an existing package.

Parameters

name (str) –

Name of the subpackage to add.

If provided, this will set the name attribute of the class.

class pymetacode.coding.GuiWidgetCreator

Bases: object

Add a PySide6-based (Qt6) GUI widget to an existing GUI subpackage.

Actually, adding a GUI window consists of creating a number of files:

  1. the module used to call the GUI window

  2. an accompanying test module

  3. the API documentation file

The latter gets added to the API toctree directive as well.

If you try to add an already existing GUI widget, a warning is raised and no further action taken, in order not to overwrite existing code.

configuration

Configuration as usually read from the configuration file.

Type

pymetacode.configuration.Configuration

Raises

ValueError – Raised if no name is provided

Examples

The following example demonstrates how to use the CLI from the terminal, rather than how to use this class programmatically, as this is the preferred and intended use case.

Prerequisite for using the CLI is to have the package configuration stored within the package root directory in the file “.project_configuration.yaml”. This will be the case if the package has been created by the CLI as well. Furthermore, all following CLI commands need to be issued from within the root directory of your package.

pymeta add widget mywidget

This will add the GUI widget mywidget to the gui subpackage of your package, together with the test_mywidget module in the tests.gui directory. Furthermore, the API documentation will be updated as well for you.

New in version 0.5.

property name

Name of the GUI widget to be created.

A suffix “widget” gets added if not present, and the name is ensured to be in lowercase letters.

Returns

name – Name of the GUI widget to be created.

Return type

str

property class_name

The name of the class containing the GUI widget.

Similar to name, but in CamelCase with the first letter capitalised and the suffix “Widget”.

Returns

class_name – The name of the class containing the GUI widget.

Return type

str

create(name='')

Add a widget to an existing GUI.

Parameters

name (str) –

Name of the widget to add.

If provided, this will set the name attribute of the class.

class pymetacode.coding.GuiDialogCreator

Bases: object

Add a PySide6-based (Qt6) GUI widget to an existing GUI subpackage.

Actually, adding a GUI window consists of creating a number of files:

  1. the module used to call the GUI window

  2. an accompanying test module

  3. the API documentation file

The latter gets added to the API toctree directive as well.

If you try to add an already existing GUI widget, a warning is raised and no further action taken, in order not to overwrite existing code.

configuration

Configuration as usually read from the configuration file.

Type

pymetacode.configuration.Configuration

Raises

ValueError – Raised if no name is provided

Examples

The following example demonstrates how to use the CLI from the terminal, rather than how to use this class programmatically, as this is the preferred and intended use case.

Prerequisite for using the CLI is to have the package configuration stored within the package root directory in the file “.project_configuration.yaml”. This will be the case if the package has been created by the CLI as well. Furthermore, all following CLI commands need to be issued from within the root directory of your package.

pymeta add dialog mydialog

This will add the GUI widget mydialog to the gui subpackage of your package, together with the test_mydialog module in the tests.gui directory. Furthermore, the API documentation will be updated as well for you.

New in version 0.5.

property name

Name of the GUI dialog to be created.

A suffix “dialog” gets added if not present, and the name is ensured to be in lowercase letters.

Returns

name – Name of the GUI dialog to be created.

Return type

str

property class_name

The name of the class containing the GUI dialog.

Similar to name, but in CamelCase with the first letter capitalised and the suffix “Dialog”.

Returns

class_name – The name of the class containing the GUI dialog.

Return type

str

create(name='')

Add a dialog to an existing GUI.

Parameters

name (str) –

Name of the dialog to add.

If provided, this will set the name attribute of the class.