A fully customizable Python application to bootstrap Poetry-based boilerplate for you to start developing your Python applications quicker! Includes linting and Pytest libraries.
It will create a new directory for your project (or use the current directory), initialise a git repository, create a virtual environment, and install some basic dependencies for Testing, Linting and more. Optionally, it can also create a GitHub repository for you and push the initial commit.
The generated project includes pytest and some related plugins to allow you to set up testing straight away.
Write your tests in the tests directory and run them with pytest.
Linting
The generated project includes Ruff for linting and code style formatting. Mypy is installed for type checking. These are set quite strictly by default, but you can edit the tools configuration in the pyproject.toml file.
Customize the generated project
You can add extra or edited files to the generated project by adding them to the ~/.pymaker/template directory. The files in this directory will be copied into the generated project, overwriting any existing files with the same name.
It is also possible to dump the whole template into this folder or the current folder so full customization and even removal of files is possible.
Pre-commit
The generated project uses pre-commit to run some checks on the code before it is committed. This is a great tool to help keep your code clean.
To install pre-commit, run the following command from inside your venv:
A fully customizable Python application to bootstrap Poetry-based boilerplate for you to start developing your Python applications quicker! Includes linting and Pytest libraries.
It will create a new directory for your project (or use the current directory), initialise a git repository, create a virtual environment, and install some basic dependencies for Testing, Linting and more. Optionally, it can also create a GitHub repository for you and push the initial commit.
The generated project includes pytest and some related plugins to allow you to set up testing straight away.
Write your tests in the tests directory and run them with pytest.
Linting
The generated project includes Ruff for linting and code style formatting. Mypy is installed for type checking. These are set quite strictly by default, but you can edit the tools configuration in the pyproject.toml file.
Customize the generated project
You can add extra or edited files to the generated project by adding them to the ~/.pymaker/template directory. The files in this directory will be copied into the generated project, overwriting any existing files with the same name.
It is also possible to dump the whole template into this folder or the current folder so full customization and even removal of files is possible.
Pre-commit
The generated project uses pre-commit to run some checks on the code before it is committed. This is a great tool to help keep your code clean.
To install pre-commit, run the following command from inside your venv:
$ pre-commitinstall
pre-commit installed at .git/hooks/pre-commit
GitHub Actions and Configuration
By default the generated project includes a GitHub Actions workflow to run Dependabot to keep your dependencies up to date. There are also standard templates for Pull Request and Issues.
The plan is to add more workflows in the future, for example running tests and more.
Changelog Generator
Once you have at least one GitHub release, you can generate a CHANGELOG.md file automatically from this, using the included github-changelog-md tool.
You can run this manually by running the following command from inside your virtual environment:
$ poechangelog
You need to have a GitHub Personal Access Token set in the config file, see the instructions here for more information.
Community related files
To aid in community building, the generated project includes a CODE_OF_CONDUCT.md file. This is based on the Contributor Covenant standard.
Future releases will include other Community related files (for example an AUTHORS file). There are also blank CONTRIBUTING.md and CHANGELOG.md files. The CHANGELOG.md file can be auto-generated.
Contributing to this Project
For information on how to contribute to the project, see the CONTRIBUTING.md file in the root of the repository or on this website
\ No newline at end of file
diff --git a/search/search_index.json b/search/search_index.json
index e1904516..7607d848 100644
--- a/search/search_index.json
+++ b/search/search_index.json
@@ -1 +1 @@
-{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Python Project Generation Tool","text":"
A fully customizable Python application to bootstrap Poetry-based boilerplate for you to start developing your Python applications quicker! Includes linting and Pytest libraries.
It will create a new directory for your project (or use the current directory), initialise a git repository, create a virtual environment, and install some basic dependencies for Testing, Linting and more. Optionally, it can also create a GitHub repository for you and push the initial commit.
The generated project includes Ruff for linting and code style formatting. Mypy is installed for type checking. These are set quite strictly by default, but you can edit the tools configuration in the pyproject.toml file.
"},{"location":"#customize-the-generated-project","title":"Customize the generated project","text":"
You can add extra or edited files to the generated project by adding them to the ~/.pymaker/template directory. The files in this directory will be copied into the generated project, overwriting any existing files with the same name.
It is also possible to dump the whole template into this folder or the current folder so full customization and even removal of files is possible.
The generated project uses pre-commit to run some checks on the code before it is committed. This is a great tool to help keep your code clean.
To install pre-commit, run the following command from inside your venv:
$ pre-commit install\npre-commit installed at .git/hooks/pre-commit\n
"},{"location":"#github-actions-and-configuration","title":"GitHub Actions and Configuration","text":"
By default the generated project includes a GitHub Actions workflow to run Dependabot to keep your dependencies up to date. There are also standard templates for Pull Request and Issues.
The plan is to add more workflows in the future, for example running tests and more.
Once you have at least one GitHub release, you can generate a CHANGELOG.md file automatically from this, using the included github-changelog-md tool.
You can run this manually by running the following command from inside your virtual environment:
$ poe changelog\n
You need to have a GitHub Personal Access Token set in the config file, see the instructions here for more information.
"},{"location":"#community-related-files","title":"Community related files","text":"
To aid in community building, the generated project includes a CODE_OF_CONDUCT.md file. This is based on the Contributor Covenant standard.
Future releases will include other Community related files (for example an AUTHORS file). There are also blank CONTRIBUTING.md and CHANGELOG.md files. The CHANGELOG.md file can be auto-generated.
"},{"location":"#contributing-to-this-project","title":"Contributing to this Project","text":"
For information on how to contribute to the project, see the CONTRIBUTING.md file in the root of the repository or on this website
This app needs minimal configuration, most options default to True. The configuration is stored in a TOML file in a sub-folder of the user's home directory. By default (and currently the only option) this file is stored in ~/.pymaker/config.toml. An example of this file is:
If this file does not exist, it will be created on first run. The app will ask for the values of author_name, author_email, default_license and github_username. For author_name and author_email it will try to use the current global git user name and email if they are set as defaults, though the user can override these.
The following options are available for configuring Py-Maker:
author_email: The email address of the author.
author_name: The name of the author.
default_license: The default license to use for the project.
github_username: The GitHub username of the author [optional].
github_token: The GitHub Personal Access Token of the author [optional]. See below for more information.
github_protocol: The protocol to use for GitHub, either ssh or https, defaults to ssh which means that the user will need to have set up an SSH key with GitHub and added it to their account. If you wish to use HTTPS, you will be asked for your GitHub password every time you push to the remote repository.
include_linters: Whether to include linters in the project, defaults to true
include_mkdocs: Whether to include MkDocs in the project, defaults to true
include_testing: Whether to include testing in the project, defaults to true
install_pre_commit: Whether to install pre-commit hooks, defaults to true
schema_version: The version of the configuration schema. This should not be modified by hand. Currently, and until version 1.0 is released, this is set to \"none\" to indicate that the schema is not yet stable.
template_folder: The path to the template folder.
use_default_template: Whether to use the default template, defaults to true
use_git: Whether to use Git for version control, defaults to true
create_remote: Whether to create a remote repository on GitHub, defaults to true
All of the boolean options are set to true by default. The template_folder is set to the default template folder, which is ~/.pymaker/template. The schema_version is for internal use, and should not be changed by the user.
You can list the current configuration with the command:
$ pymaker config show\n
"},{"location":"configuration/#edit-the-configuration-file","title":"Edit the configuration file","text":"
You can edit the configuration file with the command:
$ pymaker config edit\n
This will open the configuration file in your default editor. Under linux it will try to use xdg-open to open the file, and if that fails, it will try to use a few different editors until it finds one that works. Under Windows and Mac it will try to use the default editor.
You may also edit the configuration file manually, by default it is stored in ~/.pymaker/config.toml.
The configuration is set the first time you run the app, but you can change these defaults at any time using the command:
$ pymaker config change\n
The latter command will prompt you for the values of Author name, Author Email, Default License and GitHub Username, then update the configuration file.
"},{"location":"configuration/#add-a-github-personal-access-token","title":"Add a GitHub Personal Access Token","text":"
This app is able to create a new GitHub repository for you. To do this, it will need a GitHub Personal Access Token. You can create a new token by going to GitHub Personal Access Tokens and clicking on the \"Generate new token\" button. Use the 'Classic' token option unless you really need more control. Unless you want to use the token on Private repositories, you should check the public_repo option and leave all the other permissions unchecked (this tool does not yet have the option to create a private repository). Give it a name (for your reference only) and chose an expiry date. You can choose never to expire, but this is not recommended. Once you have created the token, copy it (it will only be shown once, so make sure you copy it now). Then run the command:
$ pymaker config token\n
This will accept the token and store it in the configuration file. You can change the token at any time by running the same command again.
NEVER PUSH THE CONFIG FILE TO A REPOSITORY!!!
This shouldnt ever happen since the file is stored in the user's home directory, but it is worth mentioning. If you didn't choose any extra permissions, then the worst that can happen is that someone can use your token to create a new repository. This token is READ-ONLY, so it can't be used to do anything malicious, but it is still a good idea to keep it secret.
"},{"location":"configuration/#manually-editing-the-configuration-file","title":"Manually editing the configuration file","text":"
The configuration file is stored in TOML format, and can be edited manually if you wish. The file is stored in ~/.pymaker/config.toml by default. The configuration file is created on first run, so if you have not run the app yet, you will need to create the file manually.
"},{"location":"contributing/","title":"Contributing","text":""},{"location":"contributing/#contributing-to-py-maker","title":"Contributing to Py-Maker","text":"
Thank you for your interest in contributing to Py-Maker! We welcome all contributions, big or small.
If you are not sure where to start, please take a look at the open issues. If you have an idea for a new feature or would like to report a bug, please open a new issue. You can also check the TODO List for ideas.
I also welcome contributions to the documentation. If you find any errors or would like to suggest improvements, please open a new issue or submit a Pull Request.
I you would like to contribute to the code, but find the requirements below a bit daunting, please feel free to open a discussion and I can help you get started, or even pair on a PR.
Since this is a Python project, you will need to have Python installed on your machine. You can download the latest version of Python from the official website or using your Operating system's package manager. This project requires Python 3.9 or higher.
I'd recommend using pyenv to manage your Python installations, the pyenv-installer works for Linux and Mac OS X. For Windows, you can use the pyenv-win port. See here for installation instructions.
We also use Poetry to manage our dependencies. You should have this installed as well. You can install Poetry by following the instructions on the Poetry website.
Run the following command to install the required dependencies:
$ poetry install\n
You then need to activate the virtual environment:
$ poetry shell\n
From here you can start working on the project. If you are using an IDE such as VSCode or PyCharm, you can set the use their Python interpreter setting to use the virtual environment that has just been created.
I am quite strict about linting and code formatting and have set up a number of pre-commit hooks and tasks to ensure that the code meets the required standards.
Use the poe ruff, poe format and poe mypy tasks regularly. If you use VSCode, install the Ruff andMyPy extensions and set them to run on save. The included .vscode folder has the settings for this.
Please install this if you are intending to contribute to the project. It will check commits locally before they are pushed up to the Repo. The GitHub CI runs the linting checks (and in future probably MyPy as well), and will fail if there are any errors.
$ pre-commit install\npre-commit installed at .git/hooks/pre-commit\n
This will ensure that all code meets the required linting standard before being committed.
At the moment the test framework is set up but we only have about 50% coverage. We will be adding more tests as we go along - and most definitely welcome any contributions to this area!
If you add any new features, please add tests for them. This will help us to ensure that the code is working as expected and will prevent any regressions. Currently we are not enforcing this until we have better coverage of the code - however if you break any existing tests, the CI will fail.
There is a task set up to run tests:
$ poe test\n
You can also run the tests manually using the following command:
$ pytest\n
The task is set up so we can automatically add other options in the future.
The changelog is automatically generated, using this project, so please do not edit it manually.
For maintainers, there is a POE task that will run this and update the changelog file.
$ poe changelog\n
You would also need to add a GitHub Personal Access Token to a local config file as usual. See the section in the Documentation for information.
However, you should NOT include a change to the CHANGELOG.md file in any Pull Requests. This will be handled by the maintainers when a new release is made. Your GitHub username will be added to the changelog automatically beside your PR.
Here are some guidelines to follow when contributing to github-changelog-md:
Follow the PEP 8 style guide. The pre-commit hooks will check for this. We are using the Ruff Formatter.
Fix any linting errors or warnings. The pre-commit hooks will check for this also. Ruff is installed and set to pretty strict settings. Ruff now replaces all the original linters that were installed. There is also a Markdown linter.
MyPy is installed and we are using type hints. Please try to add type hints to your code. If you see any areas of the code that are missing type hints, please feel free to open a PR and add them \ud83d\ude01!
Write clear and concise commit messages.
Write tests for your code.
Make sure your code passes all existing and new tests before submitting a pull request.
Document your code using docstrings. This project uses the Google Docstring Spec though at this time is a bit slack on listing the Args and Returns. I will be adding these in as I go along so feel free to add them in if you are contributing .
If you add or change any functionality, please update the documentation accordingly.
Use GitHub issues to report bugs or suggest new features.
If you are using VSCode, there is a config file in the .vscode folder that will help you to follow these guidelines. You may need to install some extensions to get the most out of it. I'll add a list of recommended extensions here soon. The Python, MyPy and Ruff ones are very helpful (the included .vscode folder helps configure these).
Add a flag to overwrite existing files if the directory exists. Make this require confirmation. Alternately allow overwrite with confirmation if an existing/populated directory is found. Add a force flag to skip confirmation. I think DO NOT allow this when '.' is specified as this could be disastrous.
Add cmd line options to specify the project name, author, etc. so the user doesn't have to enter them manually. Not sure if this is needed once we add the CLI parameters to the config file. May be useful for automation though.
Add a command to the CLI template command to show the template files as a tree, marking whether each file/folder is from the internal templates or the user's templates.
Implement a 'plugin' functionality where we can specify modified/extra files to be added to the generated project. This would also add a command line flag (ie --django, --pydantic or --fastapi or whatever) to use that plugin, and a config setting to specify using this plugin always. Plugins could be built-in (provided with the package) or user-defined (in the users /pymaker/plugins folder or installable via pip). Have a config setting to specify which plugins are enabled.
Include an optional vscode settings file in the generated project, optimized for python projects. This could include recommended extensions.
Perhaps add AUTHORS.md skeleton.
Add a default dockerfile? Maybe a docker-compose file as well- Both for this project and for the generated projects?
Update the config CLI command to enable setting/flipping individual config settings from the command line.
check for an existing GitHub repository when the user supplies the repo name and ask for an alternative if it exists.
add option (probably using the eventual plugin functionality) to create a skeleton typer CLI app.
if it creates a new remote GitHub repo, print the GitHub URL to the console.
when creating a github repo, set the About section to the description field in the pyproject.toml file. Also can set the homepage if specified. Options to add tags?
It is best to install this package globally, rather than in a virtual environment, as it is intended to be used to create new projects. Since we are using Poetry to manage the dependencies, a virtual environment will be created for you anyway specific to each project you are creating.
It is possible to install the latest development version of the package directly from the repository. In most cases this should be safe to do, but it is possible that the development version may not be stable or have bugs. If you are having issues with the development version, please open an issue on the repository.
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
The task-runner Poe the Poet is installed in the new project as a development dependency which allows us to run simple tasks (similar to npm scripts).
These are run (from within the virtual environment) using the poe command and then the script name, for example:
$ poe pre\n
To get a list of all available tasks with a description, run:
$ poe\n
You can define your own, but there are 8 specific ones provided with the script.
pre : Run pre-commit run --all-files
ruff: Run Ruff linter on all Python files in the project.
format: Run Ruff Formatter on all Python files in the project.
mypy : Run MyPy type-checker on all Python files in the project.
markdown : Run pymarkdown on all markdown files in the project.
lint = Runs ruff, formatter, mypy, markdown in sequence
If you selected to install MkDocs with this project, then there are some extra tasks to help with that:
docs:publish : Deploy the documentation to GitHub pages.
docs:build : Build the documentation locally.
docs:serve : Serve the documentation locally. Useful during development.
docs:serve:all : As above, but allows access from other devices on the network.
There is also a task to run the tests:
$ poe test\n
Finally, you can generate you CHANGELOG.md file using:
$ poe changelog\n
These are defined in the pyproject.toml file in the [tool.poe.tasks] section. Take a look at this file if you want to add or remove tasks.
"},{"location":"usage/","title":"Using PyMaker","text":""},{"location":"usage/#create-a-new-project","title":"Create a new project","text":"
To create a new project, run the following command:
$ pymaker new <project-folder>\n
This will create a new directory with the name you provide.
You can create a new project in the current directory by using . as the project folder name. This must be an empty directory:
$ mkdir test-project\n$ cd test-project\n$ pymaker new .\n
The App will then run the steps needed to get you started quickly:
Copy the template files into the new directory
Initialise a git repository
Commit the boilerplate to Git
You will be asked a series of questions to customise the new project.
"},{"location":"usage/#choose-a-package-name-and-description","title":"Choose a package name and description","text":"
When it asks \"Package Name?\" you can choose two variants :
If you are creating a standard Python package that can optionally be uploaded to PyPI, enter a package name here. Note that underscores (\"_\") must be used as opposed to dashes (\"-\") to comply with Python package naming rules. Default is the project folder name with underscores replacing dashes, spaces or dots.
For a stand-alone tool that will not be uploaded to PyPI, or is not a library, enter '-' for the package name. In this case the main.py will just be placed in the project root and no package folder will be created or referenced. You can also specify --standalone on the command line to skip this question.
For option 1 above, the App will check if the package name is available on PyPI or if it has already been used. In the latter case, you will be asked to choose another name.
"},{"location":"usage/#command-line-options","title":"Command line options","text":"
There are a few command line options that can be used to customise the build. Command line options override any settings in the config file.
For example, if use_git = false is set in the config file, then passing --git on the command line will override this and initialise a Git repository.
"},{"location":"usage/#-y-or-yes","title":"-y or --yes","text":"
Create a test directory and add the pytest dependency plus a few related plugins to the pyproject.toml file. Default is True unless include_testing = false is set in the config file or --no-test is passed on the command line.
Add linting dependencies and configuration to the pyproject.toml file. Default is True unless include_linters = false is set in the config file or --no-lint is passed on the command line.
Add MkDocs and some plugins to the pyproject.toml file. Default is True unless include_mkdocs = false is set in the config file or --no-docs is passed on the command line.
If you choose to run poetry automatically, this will also add a customized mkdocs.yml file and create a new default MkDocs site in the docs folder. Some useful plugins are also installed and added to the mkdocs.yml file.
Create a GitHub repository and push the initial commit. Default is True unless create_remote = false is set in the config file or --no-github is passed on the command line. This option needs a GitHub Personal Access Token to be set in the config file, see here
Generate a stand-alone script instead of a package. This will place the main.py file in the project root and not create a package folder. This is useful for creating a single script that can be run from the command line. this is equivalent to entering - for the package name.
Generate a project without Testing, linting or documentation libraries and configurations. It will also NOT initialise a Git repository. Currently there is no config file option to do this automatically, you must use the command line option.
You will be asked if you want to run poetry install automatically. This will create a virtual environment and install the dependencies, plus also create a bare MkDocs site and configuration. This is the recommended option.
You will still need to run poetry shell to activate the virtual environment from inside the new project folder.
$ pymaker new secret-docs\nPyMaker - Generate a Python project skeleton.\n\nCreating a new project at /home/bathroom/secret-docs\n\nName of the Application? (Secret Docs):\nPackage Name? (Use '-' for standalone script) (secret_docs):\nDescription of the Application?: Store all the Bigly amount of secret documents\nI have in the bathroom\n\nAuthor Name? (): Orange Tango\nAuthor Email? (): bigly@spraytan.org\nApplication License? [None/Apache2/BSD3/BSD2/GPL2/GPL3/LGPL/MIT/MPL2/CDDL/EPL2] (MIT):\n\nCreating a New Python app with the below settings :\n\n Description : Store all the Bigly amount of secret documents I have in the\n bathroom\n Package Name : secret_docs\n Author : Orange Tango\n Email : bigly@straytan.org\n License : MIT\n Project Dir : /home/bathroom/secret-docs\n Name : Secret Docs\n Standalone : False\n\nIs this correct? [y/n] (y):\n\n--> Creating project folder ... Done\n\nShould I Run 'poetry install' now? [y/n] (y):\nCreating virtualenv secret-docs in /home/bathroom/secret-docs/.venv\nUpdating dependencies\nResolving dependencies... (11.6s)\n\nPackage operations: 103 installs, 1 update, 0 removals\n\n \u2022 Installing lazy-object-proxy (1.9.0)\n \u2022 Installing six (1.16.0)\n\n <snippy snip>\n\n \u2022 Installing pytest-xdist (3.3.1)\n \u2022 Installing tryceratops (2.3.2)\n\nWriting lock file\n\nInstalling the current project: secret-docs (0.1.0)\n\n--> Creating MkDocs project\nINFO - Writing config file: ./mkdocs.yml\nINFO - Writing initial docs: ./docs/index.md\n\n--> Creating Git repository ... Done\n\n--> Project created successfully.\n\nNext steps:\n\n1. Change to the project directory:\n2. Install the dependencies if not done above (creates a virtual environment):\n $ poetry install\n3. Activate the virtual environment:\n $ poetry shell\n4. Run the application:\n $ secret-docs\n5. Code!\n\nSee the README.md file for more information.\n
By default, the generated application will have a basic template that you can use to get started, this template is stored inside the package itself. It will contain all you need to get started, including a basic README.md file.
The dependency management is handled by Poetry, and we include a pyproject.toml file with several useful dependencies:
PyTest for testing, along with several useful plugins.
The Black code formatter.
The Flake8 linter, along with a good selection of plugins. It is also set up to use the pyproject.toml for it's configuration, and to work nicely with Black.
Pylint and Pydocstyle linters.
MyPy for static type checking.
Isort for sorting imports.
pre-commit for running checks before committing code.
It also contains several tasks for running the tests, linting, formatting and more. These use the Poe The Poet Poetry extension see Task Runner for more information.
"},{"location":"template/modify/","title":"Adding or Modifying files in the template","text":"
If you wish to add or change specific files in the template, you can do so by adding them to the ~/.pymaker/template folder. The files (and folders) in this folder will be copied to the root of the project when the template is generated.
Files in this global template folder will override any files in the default template, so you can for example change the README.md file, add to the .gitignore or even add a complete extra folder structure.
If you want to do a major change to the template, you can actually dump the default template to this folder and modify or delete files as you see fit. See the next section for more information on how to do this.
"},{"location":"template/replace/","title":"Replacing the Default Template","text":""},{"location":"template/replace/#dump-the-default-template","title":"Dump the Default Template","text":"
Should you wish to heavily modify the default template, or even replace it completely, you can do so by dumping the default template to the ~/.pymaker/template folder. This will copy all files from the default template to the global template folder, where you can modify or delete them as you see fit.
To do this, run the following command:
$ pymaker template dump\n
This will copy the default template to the global template folder (~/.pymaker/template). You can then modify or delete files as you see fit.
Running this command will ask you if you wish to set this exported template as the default template. It will then ask you if you want to disable the internal template. If you answer yes, then the internal template will be disabled, and ONLY the exported template will be used instead. Otherwise, both will still be used with the exported template taking precedence.
"},{"location":"template/replace/#change-the-location-of-the-template-folder","title":"Change the location of the Template folder","text":"
If you wish to change the location of the template folder, you can do so in 2 ways:
By adding the --local flag to the above command (e.g. pymaker template dump --local). This will dump the default template to the current folder, giving you the option to disable the default template if needed. Note that any files in the folder will be overwritten.
By changing to the folder containing your template and running pymaker template set. This will set the current folder as the template folder and give you the same option to disable the default template.
You can reset the template location back to the default ~/.pymaker/template folder by running the following command:
$ pymaker template reset\n
"},{"location":"template/replace/#choose-to-use-the-default-template-or-not","title":"Choose to use the Default Template or not","text":"
Running the dump command will give you the option to disable the default template completely and ONLY use the exported (or custom) template. You can also do this (or revert back to the default template) by running the following command:
$ pymaker template default <enable|disable>\n
enable will enable the default template, and disable will disable it. Please note that any custom templates you have created will be used regardless, and will overwrite the default template (if enabled) if they have the same file name.
"}]}
\ No newline at end of file
+{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Python Project Generation Tool","text":"
A fully customizable Python application to bootstrap Poetry-based boilerplate for you to start developing your Python applications quicker! Includes linting and Pytest libraries.
It will create a new directory for your project (or use the current directory), initialise a git repository, create a virtual environment, and install some basic dependencies for Testing, Linting and more. Optionally, it can also create a GitHub repository for you and push the initial commit.
The generated project includes Ruff for linting and code style formatting. Mypy is installed for type checking. These are set quite strictly by default, but you can edit the tools configuration in the pyproject.toml file.
"},{"location":"#customize-the-generated-project","title":"Customize the generated project","text":"
You can add extra or edited files to the generated project by adding them to the ~/.pymaker/template directory. The files in this directory will be copied into the generated project, overwriting any existing files with the same name.
It is also possible to dump the whole template into this folder or the current folder so full customization and even removal of files is possible.
The generated project uses pre-commit to run some checks on the code before it is committed. This is a great tool to help keep your code clean.
To install pre-commit, run the following command from inside your venv:
$ pre-commit install\npre-commit installed at .git/hooks/pre-commit\n
"},{"location":"#github-actions-and-configuration","title":"GitHub Actions and Configuration","text":"
By default the generated project includes a GitHub Actions workflow to run Dependabot to keep your dependencies up to date. There are also standard templates for Pull Request and Issues.
The plan is to add more workflows in the future, for example running tests and more.
Once you have at least one GitHub release, you can generate a CHANGELOG.md file automatically from this, using the included github-changelog-md tool.
You can run this manually by running the following command from inside your virtual environment:
$ poe changelog\n
You need to have a GitHub Personal Access Token set in the config file, see the instructions here for more information.
"},{"location":"#community-related-files","title":"Community related files","text":"
To aid in community building, the generated project includes a CODE_OF_CONDUCT.md file. This is based on the Contributor Covenant standard.
Future releases will include other Community related files (for example an AUTHORS file). There are also blank CONTRIBUTING.md and CHANGELOG.md files. The CHANGELOG.md file can be auto-generated.
"},{"location":"#contributing-to-this-project","title":"Contributing to this Project","text":"
For information on how to contribute to the project, see the CONTRIBUTING.md file in the root of the repository or on this website
This app needs minimal configuration, most options default to True. The configuration is stored in a TOML file in a sub-folder of the user's home directory. By default (and currently the only option) this file is stored in ~/.pymaker/config.toml. An example of this file is:
If this file does not exist, it will be created on first run. The app will ask for the values of author_name, author_email, default_license and github_username. For author_name and author_email it will try to use the current global git user name and email if they are set as defaults, though the user can override these.
The following options are available for configuring Py-Maker:
author_email: The email address of the author.
author_name: The name of the author.
default_license: The default license to use for the project.
github_username: The GitHub username of the author [optional].
github_token: The GitHub Personal Access Token of the author [optional]. See below for more information.
github_protocol: The protocol to use for GitHub, either ssh or https, defaults to ssh which means that the user will need to have set up an SSH key with GitHub and added it to their account. If you wish to use HTTPS, you will be asked for your GitHub password every time you push to the remote repository.
include_linters: Whether to include linters in the project, defaults to true
include_mkdocs: Whether to include MkDocs in the project, defaults to true
include_testing: Whether to include testing in the project, defaults to true
install_pre_commit: Whether to install pre-commit hooks, defaults to true
schema_version: The version of the configuration schema. This should not be modified by hand. Currently, and until version 1.0 is released, this is set to \"none\" to indicate that the schema is not yet stable.
template_folder: The path to the template folder.
use_default_template: Whether to use the default template, defaults to true
use_git: Whether to use Git for version control, defaults to true
create_remote: Whether to create a remote repository on GitHub, defaults to true
All of the boolean options are set to true by default. The template_folder is set to the default template folder, which is ~/.pymaker/template. The schema_version is for internal use, and should not be changed by the user.
You can list the current configuration with the command:
$ pymaker config show\n
"},{"location":"configuration/#edit-the-configuration-file","title":"Edit the configuration file","text":"
You can edit the configuration file with the command:
$ pymaker config edit\n
This will open the configuration file in your default editor. Under linux it will try to use xdg-open to open the file, and if that fails, it will try to use a few different editors until it finds one that works. Under Windows and Mac it will try to use the default editor.
You may also edit the configuration file manually, by default it is stored in ~/.pymaker/config.toml.
The configuration is set the first time you run the app, but you can change these defaults at any time using the command:
$ pymaker config change\n
The latter command will prompt you for the values of Author name, Author Email, Default License and GitHub Username, then update the configuration file.
"},{"location":"configuration/#add-a-github-personal-access-token","title":"Add a GitHub Personal Access Token","text":"
This app is able to create a new GitHub repository for you. To do this, it will need a GitHub Personal Access Token. You can create a new token by going to GitHub Personal Access Tokens and clicking on the \"Generate new token\" button. Use the 'Classic' token option unless you really need more control. Unless you want to use the token on Private repositories, you should check the public_repo option and leave all the other permissions unchecked (this tool does not yet have the option to create a private repository). Give it a name (for your reference only) and chose an expiry date. You can choose never to expire, but this is not recommended. Once you have created the token, copy it (it will only be shown once, so make sure you copy it now). Then run the command:
$ pymaker config token\n
This will accept the token and store it in the configuration file. You can change the token at any time by running the same command again.
NEVER PUSH THE CONFIG FILE TO A REPOSITORY!!!
This shouldnt ever happen since the file is stored in the user's home directory, but it is worth mentioning. If you didn't choose any extra permissions, then the worst that can happen is that someone can use your token to create a new repository. This token is READ-ONLY, so it can't be used to do anything malicious, but it is still a good idea to keep it secret.
"},{"location":"configuration/#manually-editing-the-configuration-file","title":"Manually editing the configuration file","text":"
The configuration file is stored in TOML format, and can be edited manually if you wish. The file is stored in ~/.pymaker/config.toml by default. The configuration file is created on first run, so if you have not run the app yet, you will need to create the file manually.
"},{"location":"contributing/","title":"Contributing","text":""},{"location":"contributing/#contributing-to-py-maker","title":"Contributing to Py-Maker","text":"
Thank you for your interest in contributing to Py-Maker! We welcome all contributions, big or small.
If you are not sure where to start, please take a look at the open issues. If you have an idea for a new feature or would like to report a bug, please open a new issue. You can also check the TODO List for ideas.
I also welcome contributions to the documentation. If you find any errors or would like to suggest improvements, please open a new issue or submit a Pull Request.
I you would like to contribute to the code, but find the requirements below a bit daunting, please feel free to open a discussion and I can help you get started, or even pair on a PR.
Since this is a Python project, you will need to have Python installed on your machine. You can download the latest version of Python from the official website or using your Operating system's package manager. This project requires Python 3.9 or higher.
I'd recommend using pyenv to manage your Python installations, the pyenv-installer works for Linux and Mac OS X. For Windows, you can use the pyenv-win port. See here for installation instructions.
We also use Poetry to manage our dependencies. You should have this installed as well. You can install Poetry by following the instructions on the Poetry website.
Run the following command to install the required dependencies:
$ poetry install\n
You then need to activate the virtual environment:
$ poetry shell\n
From here you can start working on the project. If you are using an IDE such as VSCode or PyCharm, you can set the use their Python interpreter setting to use the virtual environment that has just been created.
I am quite strict about linting and code formatting and have set up a number of pre-commit hooks and tasks to ensure that the code meets the required standards.
Use the poe ruff, poe format and poe mypy tasks regularly. If you use VSCode, install the Ruff andMyPy extensions and set them to run on save. The included .vscode folder has the settings for this.
Please install this if you are intending to contribute to the project. It will check commits locally before they are pushed up to the Repo. The GitHub CI runs the linting checks (and in future probably MyPy as well), and will fail if there are any errors.
$ pre-commit install\npre-commit installed at .git/hooks/pre-commit\n
This will ensure that all code meets the required linting standard before being committed.
At the moment the test framework is set up but we only have about 50% coverage. We will be adding more tests as we go along - and most definitely welcome any contributions to this area!
If you add any new features, please add tests for them. This will help us to ensure that the code is working as expected and will prevent any regressions. Currently we are not enforcing this until we have better coverage of the code - however if you break any existing tests, the CI will fail.
There is a task set up to run tests:
$ poe test\n
You can also run the tests manually using the following command:
$ pytest\n
The task is set up so we can automatically add other options in the future.
The changelog is automatically generated, using this project, so please do not edit it manually.
For maintainers, there is a POE task that will run this and update the changelog file.
$ poe changelog\n
You would also need to add a GitHub Personal Access Token to a local config file as usual. See the section in the Documentation for information.
However, you should NOT include a change to the CHANGELOG.md file in any Pull Requests. This will be handled by the maintainers when a new release is made. Your GitHub username will be added to the changelog automatically beside your PR.
Here are some guidelines to follow when contributing to github-changelog-md:
Follow the PEP 8 style guide. The pre-commit hooks will check for this. We are using the Ruff Formatter.
Fix any linting errors or warnings. The pre-commit hooks will check for this also. Ruff is installed and set to pretty strict settings. Ruff now replaces all the original linters that were installed. There is also a Markdown linter.
MyPy is installed and we are using type hints. Please try to add type hints to your code. If you see any areas of the code that are missing type hints, please feel free to open a PR and add them \ud83d\ude01!
Write clear and concise commit messages.
Write tests for your code.
Make sure your code passes all existing and new tests before submitting a pull request.
Document your code using docstrings. This project uses the Google Docstring Spec though at this time is a bit slack on listing the Args and Returns. I will be adding these in as I go along so feel free to add them in if you are contributing .
If you add or change any functionality, please update the documentation accordingly.
Use GitHub issues to report bugs or suggest new features.
If you are using VSCode, there is a config file in the .vscode folder that will help you to follow these guidelines. You may need to install some extensions to get the most out of it. I'll add a list of recommended extensions here soon. The Python, MyPy and Ruff ones are very helpful (the included .vscode folder helps configure these).
Add a flag to overwrite existing files if the directory exists. Make this require confirmation. Alternately allow overwrite with confirmation if an existing/populated directory is found. Add a force flag to skip confirmation. I think DO NOT allow this when '.' is specified as this could be disastrous.
Add cmd line options to specify the project name, author, etc. so the user doesn't have to enter them manually. Not sure if this is needed once we add the CLI parameters to the config file. May be useful for automation though.
Add a command to the CLI template command to show the template files as a tree, marking whether each file/folder is from the internal templates or the user's templates.
Implement a 'plugin' functionality where we can specify modified/extra files to be added to the generated project. This would also add a command line flag (ie --django, --pydantic or --fastapi or whatever) to use that plugin, and a config setting to specify using this plugin always. Plugins could be built-in (provided with the package) or user-defined (in the users /pymaker/plugins folder or installable via pip). Have a config setting to specify which plugins are enabled.
Include an optional vscode settings file in the generated project, optimized for python projects. This could include recommended extensions.
Perhaps add AUTHORS.md skeleton.
Add a default dockerfile? Maybe a docker-compose file as well- Both for this project and for the generated projects?
Update the config CLI command to enable setting/flipping individual config settings from the command line.
check for an existing GitHub repository when the user supplies the repo name and ask for an alternative if it exists.
add option (probably using the eventual plugin functionality) to create a skeleton typer CLI app.
if it creates a new remote GitHub repo, print the GitHub URL to the console.
when creating a github repo, set the About section to the description field in the pyproject.toml file. Also can set the homepage if specified. Options to add tags?
It is best to install this package globally, rather than in a virtual environment, as it is intended to be used to create new projects. Since we are using Poetry to manage the dependencies, a virtual environment will be created for you anyway specific to each project you are creating.
It is possible to install the latest development version of the package directly from the repository. In most cases this should be safe to do, but it is possible that the development version may not be stable or have bugs. If you are having issues with the development version, please open an issue on the repository.
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
The task-runner Poe the Poet is installed in the new project as a development dependency which allows us to run simple tasks (similar to npm scripts).
These are run (from within the virtual environment) using the poe command and then the script name, for example:
$ poe pre\n
To get a list of all available tasks with a description, run:
$ poe\n
You can define your own, but there are 8 specific ones provided with the script.
pre : Run pre-commit run --all-files
ruff: Run Ruff linter on all Python files in the project.
format: Run Ruff Formatter on all Python files in the project.
mypy : Run MyPy type-checker on all Python files in the project.
markdown : Run pymarkdown on all markdown files in the project.
lint = Runs ruff, formatter, mypy, markdown in sequence
If you selected to install MkDocs with this project, then there are some extra tasks to help with that:
docs:publish : Deploy the documentation to GitHub pages.
docs:build : Build the documentation locally.
docs:serve : Serve the documentation locally. Useful during development.
docs:serve:all : As above, but allows access from other devices on the network.
There is also a task to run the tests:
$ poe test\n
Finally, you can generate you CHANGELOG.md file using:
$ poe changelog\n
These are defined in the pyproject.toml file in the [tool.poe.tasks] section. Take a look at this file if you want to add or remove tasks.
"},{"location":"usage/","title":"Using PyMaker","text":""},{"location":"usage/#create-a-new-project","title":"Create a new project","text":"
To create a new project, run the following command:
$ pymaker new <project-folder>\n
This will create a new directory with the name you provide.
You can create a new project in the current directory by using . as the project folder name. This must be an empty directory:
$ mkdir test-project\n$ cd test-project\n$ pymaker new .\n
The App will then run the steps needed to get you started quickly:
Copy the template files into the new directory
Initialise a git repository
Commit the boilerplate to Git
You will be asked a series of questions to customise the new project.
"},{"location":"usage/#choose-a-package-name-and-description","title":"Choose a package name and description","text":"
When it asks \"Package Name?\" you can choose two variants :
If you are creating a standard Python package that can optionally be uploaded to PyPI, enter a package name here. Note that underscores (\"_\") must be used as opposed to dashes (\"-\") to comply with Python package naming rules. Default is the project folder name with underscores replacing dashes, spaces or dots.
For a stand-alone tool that will not be uploaded to PyPI, or is not a library, enter '-' for the package name. In this case the main.py will just be placed in the project root and no package folder will be created or referenced. You can also specify --standalone on the command line to skip this question.
For option 1 above, the App will check if the package name is available on PyPI or if it has already been used. In the latter case, you will be asked to choose another name.
"},{"location":"usage/#command-line-options","title":"Command line options","text":"
There are a few command line options that can be used to customise the build. Command line options override any settings in the config file.
For example, if use_git = false is set in the config file, then passing --git on the command line will override this and initialise a Git repository.
"},{"location":"usage/#-y-or-yes","title":"-y or --yes","text":"
Create a test directory and add the pytest dependency plus a few related plugins to the pyproject.toml file. Default is True unless include_testing = false is set in the config file or --no-test is passed on the command line.
Add linting dependencies and configuration to the pyproject.toml file. Default is True unless include_linters = false is set in the config file or --no-lint is passed on the command line.
Add MkDocs and some plugins to the pyproject.toml file. Default is True unless include_mkdocs = false is set in the config file or --no-docs is passed on the command line.
If you choose to run poetry automatically, this will also add a customized mkdocs.yml file and create a new default MkDocs site in the docs folder. Some useful plugins are also installed and added to the mkdocs.yml file.
Create a GitHub repository and push the initial commit. Default is True unless create_remote = false is set in the config file or --no-github is passed on the command line. This option needs a GitHub Personal Access Token to be set in the config file, see here
Generate a stand-alone script instead of a package. This will place the main.py file in the project root and not create a package folder. This is useful for creating a single script that can be run from the command line. this is equivalent to entering - for the package name.
Generate a project without Testing, linting or documentation libraries and configurations. It will also NOT initialise a Git repository. Currently there is no config file option to do this automatically, you must use the command line option.
You will be asked if you want to run poetry install automatically. This will create a virtual environment and install the dependencies, plus also create a bare MkDocs site and configuration. This is the recommended option.
You will still need to run poetry shell to activate the virtual environment from inside the new project folder.
$ pymaker new secret-docs\nPyMaker - Generate a Python project skeleton.\n\nCreating a new project at /home/bathroom/secret-docs\n\nName of the Application? (Secret Docs):\nPackage Name? (Use '-' for standalone script) (secret_docs):\nDescription of the Application?: Store all the Bigly amount of secret documents\nI have in the bathroom\n\nAuthor Name? (): Orange Tango\nAuthor Email? (): bigly@spraytan.org\nApplication License? [None/Apache2/BSD3/BSD2/GPL2/GPL3/LGPL/MIT/MPL2/CDDL/EPL2] (MIT):\n\nCreating a New Python app with the below settings :\n\n Description : Store all the Bigly amount of secret documents I have in the\n bathroom\n Package Name : secret_docs\n Author : Orange Tango\n Email : bigly@straytan.org\n License : MIT\n Project Dir : /home/bathroom/secret-docs\n Name : Secret Docs\n Standalone : False\n\nIs this correct? [y/n] (y):\n\n--> Creating project folder ... Done\n\nShould I Run 'poetry install' now? [y/n] (y):\nCreating virtualenv secret-docs in /home/bathroom/secret-docs/.venv\nUpdating dependencies\nResolving dependencies... (11.6s)\n\nPackage operations: 103 installs, 1 update, 0 removals\n\n \u2022 Installing lazy-object-proxy (1.9.0)\n \u2022 Installing six (1.16.0)\n\n <snippy snip>\n\n \u2022 Installing pytest-xdist (3.3.1)\n \u2022 Installing tryceratops (2.3.2)\n\nWriting lock file\n\nInstalling the current project: secret-docs (0.1.0)\n\n--> Creating MkDocs project\nINFO - Writing config file: ./mkdocs.yml\nINFO - Writing initial docs: ./docs/index.md\n\n--> Creating Git repository ... Done\n\n--> Project created successfully.\n\nNext steps:\n\n1. Change to the project directory:\n2. Install the dependencies if not done above (creates a virtual environment):\n $ poetry install\n3. Activate the virtual environment:\n $ poetry shell\n4. Run the application:\n $ secret-docs\n5. Code!\n\nSee the README.md file for more information.\n
By default, the generated application will have a basic template that you can use to get started, this template is stored inside the package itself. It will contain all you need to get started, including a basic README.md file.
The dependency management is handled by Poetry, and we include a pyproject.toml file with several useful dependencies:
PyTest for testing, along with several useful plugins.
The Black code formatter.
The Flake8 linter, along with a good selection of plugins. It is also set up to use the pyproject.toml for it's configuration, and to work nicely with Black.
Pylint and Pydocstyle linters.
MyPy for static type checking.
Isort for sorting imports.
pre-commit for running checks before committing code.
It also contains several tasks for running the tests, linting, formatting and more. These use the Poe The Poet Poetry extension see Task Runner for more information.
"},{"location":"template/modify/","title":"Adding or Modifying files in the template","text":"
If you wish to add or change specific files in the template, you can do so by adding them to the ~/.pymaker/template folder. The files (and folders) in this folder will be copied to the root of the project when the template is generated.
Files in this global template folder will override any files in the default template, so you can for example change the README.md file, add to the .gitignore or even add a complete extra folder structure.
If you want to do a major change to the template, you can actually dump the default template to this folder and modify or delete files as you see fit. See the next section for more information on how to do this.
"},{"location":"template/replace/","title":"Replacing the Default Template","text":""},{"location":"template/replace/#dump-the-default-template","title":"Dump the Default Template","text":"
Should you wish to heavily modify the default template, or even replace it completely, you can do so by dumping the default template to the ~/.pymaker/template folder. This will copy all files from the default template to the global template folder, where you can modify or delete them as you see fit.
To do this, run the following command:
$ pymaker template dump\n
This will copy the default template to the global template folder (~/.pymaker/template). You can then modify or delete files as you see fit.
Running this command will ask you if you wish to set this exported template as the default template. It will then ask you if you want to disable the internal template. If you answer yes, then the internal template will be disabled, and ONLY the exported template will be used instead. Otherwise, both will still be used with the exported template taking precedence.
"},{"location":"template/replace/#change-the-location-of-the-template-folder","title":"Change the location of the Template folder","text":"
If you wish to change the location of the template folder, you can do so in 2 ways:
By adding the --local flag to the above command (e.g. pymaker template dump --local). This will dump the default template to the current folder, giving you the option to disable the default template if needed. Note that any files in the folder will be overwritten.
By changing to the folder containing your template and running pymaker template set. This will set the current folder as the template folder and give you the same option to disable the default template.
You can reset the template location back to the default ~/.pymaker/template folder by running the following command:
$ pymaker template reset\n
"},{"location":"template/replace/#choose-to-use-the-default-template-or-not","title":"Choose to use the Default Template or not","text":"
Running the dump command will give you the option to disable the default template completely and ONLY use the exported (or custom) template. You can also do this (or revert back to the default template) by running the following command:
$ pymaker template default <enable|disable>\n
enable will enable the default template, and disable will disable it. Please note that any custom templates you have created will be used regardless, and will overwrite the default template (if enabled) if they have the same file name.
"}]}
\ No newline at end of file
diff --git a/sitemap.xml.gz b/sitemap.xml.gz
index 2c27de81..f958ddef 100644
Binary files a/sitemap.xml.gz and b/sitemap.xml.gz differ
