Skip to content

Latest commit

 

History

History
185 lines (155 loc) · 5.63 KB

README.adoc

File metadata and controls

185 lines (155 loc) · 5.63 KB
Raw

Package generator Documentation

Table of Contents

1. Introduction

The folder model_package contain a generic structure for a Python package, with setup.py and everything needed for a basic package.

1.1. Model Package info

Usefull resources:
The package is designed for:

  • Unit test with pytest

  • CI with gitlab-ci

  • readme with asciidoc

  • Python 3 only

  • logs with logging.

    • Each Python file in the package structure must have:

      import logging
LOG = logging.getLogger(__name__)

    • You must use this when printing something (error, warning, info, debug):

      LOG.debug("Here is some info")

    • At the start of your main function, you must do:

      from . import utils
utils.init_log(log={my_package}, stdout_loglevel="INFO", file_loglevel="DEBUG")

      to ensure logging properly works

  • [optional] configuration file with configobj

2. How to use

Just run the script in its directory:

./create_new_package.py --name "toto"

The package will appear in a generated folder. Copy paste everything in it where you want to put your package (in a new Git repository for instance)

For help on the script, type:

./create_new_package.py -h

3. List of Plugins available

Plugins are available. They are extra lines of code only needed when you want a specific feature.

3.1. ini file: --ini

To include this plugin, add the option --ini to the command line:

./create_new_package.py --name blabla --ini

If chosen, will add <my_package>/config.py that contain the get_config function.

Note
 This function is intended for developpers and not supposed to be used outside of the package. It’s main use is to have a reliable validation function that describe what’s going wrong with the configuration file.

Use it like this:

from . import config

params = config.get_config('my_inifile.ini')
Important
 Note that the file <my_package>/configspec.ini contain the description for your configuration file and MUST be changed.

3.2. GUI: --gui

To include this plugin, add the option --gui to the command line:

./create_new_package.py --name blabla --gui

This will create an Application class in gui.py and to launch it, you just do:

import {my_package}

{my_package}.run()

To populate your graphical interface, you are expected to change the function gui.Application.__create_widgets

4. How to make change to the model package ?

4.1. Main Package

Files in the model_package will be copied into your future package, keeping the same structure.

Generic rules:

  • Each file must end with a blanck line (mainly because of plugins, to avoid that the first line of a plugin file to be added to the last line of the original file)

  • Each time the package name must be present (either for a file/folder name, or inside the file itself), a generic tag <my_package> must be in its place. During package creation, this tag will be replaced with the name chosen for the package.

  • Each new Python file in the package must start with the following lines:

    import logging
LOG = logging.getLogger(__name__)

    === For plugins Plugin folder must respect the same structure as the main model_package. I.e. for a plugin to add lines to an existing <my_package>/utils.py file, you must create the same file, in the same sub-folder, under the plugin structure, then add the extra lines you want to add.

When a file exist in both the model and the plugin, file content in the plugin will be appended in the original file.

Important
 All files must end in a blanck line. If not, when trying to append, last line of first file and first line of second file will be mixed up in the same line

For instance, here is one structure for model_package:

model_package/
├── src
│ └── <my_package>
│    ├── __init__.py
│    ├── utils.py
│    └── version.py
├── .gitignore
├── .gitlab-ci.yml
├── README.md
└── pyproject.toml

Here is the structure of the ini_file_plugin:

ini_file_plugin/
├── src
│ └── <my_package>
│    ├── config.py
│    ├── configspec.ini
│    └── __init__.py
└── pyproject.toml
Plugin rules:

  • you don’t need to add in the plugin structures files that have not changed compared to the model package

  • you can only add lines. You can’t delete lines from the model_package via a plugin

  • When adding to a plugin a file that already exist in model_package, its lines will be added at the end of the corresponding original file

  • pyproject.toml is special, the plugin version of that file must only contain extra dependencies using the following syntax (note the extra line at the end):

        "tkinter",
    "pyinstaller",

5. FAQ

5.1. Dynamic version

I couldn’t use dynamic version until I moved "my_package" into a src directory. Before that, the dynamic version resulted in the following error:

        File "/tmp/pip-build-env-qq3zkq0q/overlay/lib/python3.10/site-packages/setuptools/config/expand.py", line 203, in _find_spec
          raise ModuleNotFoundError(module_name)
      ModuleNotFoundError: toto