{"id":30179727,"url":"https://github.com/philippmeder/pkgcreator","last_synced_at":"2025-08-12T06:16:15.770Z","repository":{"id":307142433,"uuid":"1028498057","full_name":"PhilippMeder/pkgcreator","owner":"PhilippMeder","description":"Create python package structure, necessary files with content, git repository and venv.","archived":false,"fork":false,"pushed_at":"2025-07-29T18:05:44.000Z","size":105,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-29T18:59:24.549Z","etag":null,"topics":["packaging","packaging-tool","project-structure","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/PhilippMeder.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-29T16:06:12.000Z","updated_at":"2025-07-29T18:00:57.000Z","dependencies_parsed_at":"2025-07-29T18:59:31.388Z","dependency_job_id":"859a843e-3a94-405a-9645-5ab9225d77d0","html_url":"https://github.com/PhilippMeder/pkgcreator","commit_stats":null,"previous_names":["philippmeder/pkgcreator"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/PhilippMeder/pkgcreator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PhilippMeder%2Fpkgcreator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PhilippMeder%2Fpkgcreator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PhilippMeder%2Fpkgcreator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PhilippMeder%2Fpkgcreator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PhilippMeder","download_url":"https://codeload.github.com/PhilippMeder/pkgcreator/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PhilippMeder%2Fpkgcreator/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270011217,"owners_count":24511903,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-12T02:00:09.011Z","response_time":80,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["packaging","packaging-tool","project-structure","python"],"created_at":"2025-08-12T06:16:10.557Z","updated_at":"2025-08-12T06:16:15.752Z","avatar_url":"https://github.com/PhilippMeder.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/PhilippMeder/pkgcreator/main/docs/figs/pkgcreator_logo.svg\" width=\"300\"\u003e\n\u003c/h1\u003e\n\n[![PyPi badge](https://img.shields.io/pypi/v/pkgcreator)](https://pypi.org/project/pkgcreator/)\n[![Python versions badge](https://img.shields.io/pypi/pyversions/pkgcreator.svg)](https://pypi.org/project/pkgcreator/)\n[![License badge](https://img.shields.io/pypi/l/pkgcreator.svg)](https://github.com/PhilippMeder/pkgcreator/blob/main/LICENSE)\n[![GitHub actions status badge](https://github.com/PhilippMeder/pkgcreator/actions/workflows/test-python-package.yml/badge.svg)](https://github.com/PhilippMeder/pkgcreator/actions/workflows/test-python-package.yml)\n[![GitHub issues badge](https://img.shields.io/badge/issue_tracking-github-blue.svg)](https://github.com/PhilippMeder/pkgcreator/issues)\n\n`pkgcreator` is a Python CLI tool that helps you quickly set up a new Python package with a recommended folder structure, a virtual environment, license file, Git repository, and pre-filled configuration files like `pyproject.toml` and `README.md`.\n\nIt supports interactive prompts, smart defaults (e.g. from your Git config), and includes additional utilities like a GitHub folder downloader, CLI/formatter helpers, and virtual environment management.\n\nWhether you're preparing a new project or just want a clean setup for your next internal tool — `pkgcreator` automates the boilerplate and saves you time.\n\nDeveloped and maintained by [Philipp Meder](https://github.com/PhilippMeder).\n\n- **Source code**: https://github.com/PhilippMeder/pkgcreator.git\n- **Report bugs**: https://github.com/PhilippMeder/pkgcreator/issues\n\nQuick overview:\n\n1. [Quick Start](#quick-start)\n2. [License](#license)\n3. [Features](#features) **(most interesting part)**\n4. [Requirements and Dependencies](#requirements-and-dependencies)\n\n## Quick Start\n\nInstall this package (replace `pkgcreator` with `pkgcreator[full]` to install all optional dependencies on Python packages):\n\n```bash\npip install pkgcreator\n```\n\nCreate a new package structure, initialise Git, create a virtual environment, and include the *MIT license*:\n\n```bash\npkgcreator create mypackage --git --venv --license MIT\n```\n\nFor a detailed list of available options, see the section [Package Structure Creator](#package-structure-creator).\n\n## License\n\nDistributed under the [BSD 3-Clause License](./LICENSE).\n\n## Features\n\nFollowing features are covered here, with focus on the main feature **[Package Structure Creator](#package-structure-creator)**.\n\n1. [Package Structure Creator](#package-structure-creator)\n    1. [Creating the package structure](#creating-the-package-structure)\n    2. [Configuring the creation process and adding Git/venv](#configuring-the-creation-process-and-adding-gitvenv)\n    3. [Configuring project settings](#configuring-project-settings)\n    4. [Using preselections and suggestions](#using-preselections-and-suggestions)\n2. [Accessing Git with Python](#accessing-git-with-python)\n3. [GitHub Downloader](#github-downloader)\n    1. [Python version](#python-version)\n    2. [Bash version](#bash-version)\n4. [Creating and Managing Virtual Environments](#creating-and-managing-virtual-environments)\n5. [Tools](#tools)\n    1. [Logging tools](#logging-tools)\n    2. [CLI tools](#cli-tools)\n\nTo use the core features, you may directly call one of the two following lines:\n\n```bash\npkgcreator [OPTIONS]\npython -m pkgcreator [OPTIONS]\n```\n\nFor a list of available options, see the next sections or run:\n\n```bash\npkgcreator --help\n```\n\n### Package Structure Creator\n\nCreate a typical file structure for a python package with the necessary files and their content.\n\n#### Creating the package structure\n\nRunning `pkgcreator create \u003cNAME\u003e` will create the following package structure as officially recommended:\n\n- `NAME`\n  - `src/NAME`\n    - `__init__.py`\n    - `__main__.py` (if the `--script` option is used)\n  - `.gitignore` (with some presets)\n  - `LICENSE` (with content if the `-l, --license\u003e` option is used)\n  - `pyproject.toml` (with content according to the options used, see `--help`)\n  - `README.md` (with content according to the options used, see `--help`)\n\nFor a list of available options, read the next sections or run:\n\n```bash\npkgcreator create --help\n```\n\n#### Configuring the creation process and adding Git/venv\n\nThere are several important options you may consider when creating the package structure:\n\n- Adding a license text with `--license \u003cLICENSE\u003e`:\n\n  Using the `-l, --license \u003cLICENSE\u003e` option allows you to add the text of `\u003cLICENSE\u003e` if this is a valid identifier. To list all available identifiers, use `--list-licenses`. This option requires the python package `requests` and will fail if it is not installed.\n\n- Initialising a Git repository with `--git`:\n\n  If `Git` is available on your system, using the `--git` option automatically initialises a Git repository and commits all created files.\n\n- Creating a virtual environment with `--venv`:\n\n  Using the `--venv` option automatically creates a virtual environment in `NAME/.venv` (ignored by `Git`) and installs the created package in editable mode so you can run it as `python -m \u003cNAME\u003e` or import it with `import \u003cNAME\u003e` inside the activated environment.\n\n- Providing the package as a script with `--script`:\n\n  Using the `--script` option will create a `__main__.py` with function `main()` that is called whenever you run the package as a module (`python -m \u003cNAME\u003e`). In addition, the `pyproject.toml` registers the terminal command `\u003cNAME\u003e` that will also call this function.\n\n#### Using preselections and suggestions\n\nIf not explicitly set, some arguments will suggest values based on context:\n\n- `--github-repositoryname` may suggest using the package name\n- `--author-name` may suggest using `user.name` from `git config`, if available\n- `--author-mail` may suggest using `user.email` from `git config`, if available\n- `--git` may ask whether to initialise a Git repository\n- `--venv` may ask whether to initialise a virtual environment and install the package in editable mode\n\nUse the `-m, --prompt-mode` option to control whether these suggestions are shown or automatically handled:\n\n| Option                   | `yes` | `auto` | `no`  |\n|--------------------------|:-----:|:------:|:-----:|\n| `--github-repositoryname`|  ✅   |   ✅    |  ❌   |\n| `--author-name`          |  ✅   |   ✅    |  ❌   |\n| `--author-mail`          |  ✅   |   ✅    |  ❌   |\n| `--git`                  |  ✅   |   ❌    |  ❌   |\n| `--venv`                 |  ✅   |   ❌    |  ❌   |\n\n- `yes`: Automatically accept all suggestions\n- `no`: Skip all prompts and use defaults or leave unset\n- `auto`: Accept safe suggestions only (e.g., use Git info, but skip Git initialisation)\n- `ask` *(default)*: Prompt interactively for each case, and ask again before creating the project structure\n\n#### Configuring project settings\n\nThere are a bunch of variables that are used for the creation of the `pyproject.toml`, `README.md`, and `LICENSE` (if `-l` is used).\n\n**These can be changed later in the mentioned files.**\n\nAvailable options are (the names are self-explanatory):\n\n| Option |  Notes |\n|--------|------------|\n| `--description` |   |\n| `--author-name` | suggests `git config user.name` if not set |\n| `--author-mail` | suggests `git config user.email` if not set |\n| `--github-username` | used for various project URLs (if not provided) |\n| `--github-repositoryname` | used for various project URLs (if not provided), suggests the package name if not set |\n\nIn addition, a typical package also links to some of its online resources.\nIf not set, each of them will link to a subpage of the github repository defined by `--github-username` and `--github-repositoryname`.\n\n- `--changelog`\n- `--documentation`\n- `--download`\n- `--funding`\n- `--homepage`\n- `--issues`\n- `--releasenotes`\n- `--source`\n\nIf some dependencies, optional dependencies or classifiers (for PyPI) are already known, they can be set with the following commands:\n\n- `--dependencies package1 package2 ...`\n- `--optional-dependencies package1 package2 ...` (available as a `[full]` option during package installation)\n- `--classifiers classifier1 classifier2 ...` (for a full list see [PyPI classifier](https://pypi.org/classifiers/))\n\n### Accessing Git with Python\n\nThis feature is provided for completeness since it is used as a handy tool during the package structure creation process.\nYou may run\n\n```bash\npkgcreator git --help\n```\n\nto list the available options.\nHowever, **running Git directly** is usually more flexible and preferred.\n\n### GitHub Downloader\n\nDownload a specific folder (or the entire contents) from a public GitHub repository using the GitHub API.\n\n#### Python version\n\n**Features:**\n\n* Downloads a subfolder or the full repository\n* Supports branch selection\n* Recursive or non-recursive download\n\n**Usage:**\n\nTo download the repository contents (default branch `main`), run:\n\n```bash\npkgcreator github-download \u003cOWNER\u003e \u003cREPOSITORY\u003e [OPTIONS]\n```\n\nAvailable options are (run `pkgcreator github-download --help` for a full list):\n\n- `-b, --branch` Selects the branch name (default: *main*).\n- `-s, --subfolder` If not provided, download the full repository. If set to a subdirectory of the repository, download this subdirectory. If set to a single file, only download this file.\n- `-d, --destination` Local directory where the files should be downloaded to (default: *./downloaded_\u003cREPOSITORY\u003e*).\n- `-n, --no-recursive` Do not download folders recursively.\n- `--list` List the content of the repository (or the given subfolder) and exit.\n\n**Note:** The GitHub API limits the number of requests per time period. For more information see the [Rate limits for the REST API](https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api).\n\n#### Bash version\n\nFor completeness, a bash version is provided.\n\nLocated in: [`github_download.sh`](./scripts/github_download.sh)\n\n**Features:**\n\n* Uses `git sparse-checkout` to efficiently fetch only a folder\n* Minimal download size, ideal for large repositories\n\n**Usage:**\n\n```bash\n./github_download.sh ExampleOwner example_repo main ./target_folder subdir/in/repo\n```\n\nArguments:\n\n```text\n\u003cowner\u003e \u003crepo\u003e [branch=main] [target_dir=\u003crepo\u003e_sparse] [folder=None]\n```\n\nIf no folder is specified, the full repository is checked out.\n\n### Creating and Managing Virtual Environments\n\nThe command\n\n```bash\npkgcreator venv [OPTIONS]\n```\n\ncan create a virtual environment and install packages in this environment.\nAvailable options are (run `pkgcreator github-download --help` for a full list):\n\n- `-d, --destination` Directory where the venv folder will be created (default: current working directory).\n- `-c, --create` Create the virtual environment.\n- `-i, --install` List of packages to install (via pip).\n- `-e, --editable` List of packages/local package paths to install in editable mode (-e).\n- `--name` Name of the virtual environment folder (default: .venv).\n- `--version-suffix` Append Python major/minor version to the venv folder name.\n\n### Tools\n\nIn addition to the main features, also some useful tools that were written for the functionality of this package are available.\n\n#### Logging tools\n\n- `LoggerFormatter` provides a formatter that is a subclass of the standard library's `logging.Formatter`. The logger messages will be color coded and start with `[Error], [Warning], [Info]` depending on the message type.\n- `logged_subprocess_run` provides a wrapper around `subprocess.run` where the output feed of the process is streamed live to the given logger.\n\nTo use these features and understand their parameters, run:\n\n```python\nfrom pkgcreator.logging_tools import LoggerFormatter, logged_subprocess_run\n\nhelp(LoggerFormatter)\nhelp(logged_subprocess_run)\n```\n\n#### CLI tools\n\n- `ConsistentFormatter` provides an `argparse.HelpFormatter` that aims at a consistent appearance. It enforces capitalization and periods where needed.\n- `generate_parser_template` generates a template Python function that consistently creates an `argparse.Argparser` that is either a standalone or a subparser.\n\nTo use these features and understand their parameters, run:\n\n```python\nfrom pkgcreator.cli_tools import ConsistentFormatter, generate_parser_template\n\nhelp(ConsistentFormatter)\nhelp(generate_parser_template)\n```\n\n## Requirements and Dependencies\n\nFollowing **requirements** must be satisfied:\n\n* `Python 3.10+` (developed with `Python 3.13`, tested with `Python 3.10+`, lower version are not working due to the use of `match ... case` and `Union`)\n\nFollowing **optional dependencies** are recommended, but not required:\n\n* `requests` library (for Python GitHub downloader and license selection/download)\n* `Git` (for sparse-checkout Bash script or if you want to initialise a Git repository when creating a Python package)\n\nTo install Python dependencies you may either use\n\n```bash\npip install DEPENDENCY\n```\n\nor directly specify that you want to install all optional dependencies when installing this package with:\n\n```bash\npip install pkgcreator[full]\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphilippmeder%2Fpkgcreator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fphilippmeder%2Fpkgcreator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphilippmeder%2Fpkgcreator/lists"}