# wads
Tools for packaging and publishing to pypi for those who just don't want to deal with it
To install (for example):
```
pip install wads
```
# Table of Contents
- [Usage Examples](#usage-examples)
- [populate](#populate)
- [pack](#pack)
- [Migration Tools](#migration-tools) - **NEW!** Migrate old projects to modern format
- [Troubleshooting](#troubleshooting)
# Usage Examples
We're going to assume you pointed "pack" to "wads/pack.py" and "populate" to "wads/populate.py",
because it's convenient for us to do so. You can achieve this in various ways
(for example, putting the contents:
`python /Users/Thor.Whalen/Dropbox/dev/p3/proj/i/wads/wads/pack.py "$@"`
in a file named "pack" contained in your OS's script path.)
## populate
When? When you got a new project and you want to quickly set it up with the packaging goodies.
Basic usage:
```
populate PKG_DIR
```
or, assuming you're using the terminal and you're in the `PKG_DIR` root folder of the project, you can just do:
```
populate .
```
What that will do is create and populate some files for you.
Namely, it will ensure your package directory has the following files (if not present already)
```
./LICENSE
./setup.cfg
./PKG_NAME/__init__.py
./README.md
```
The `PKG_NAME` will be taken to be the same as the name of the `PKG_DIR`.
That will work, it will be minimal and will choose defaults for you.
You can overwrite many of these, of course.
For example,
```
populate -r https:///github.com/i2mint --description "Something about my project..."
```
Here are the following options:
```
positional arguments:
pkg-dir -
optional arguments:
-h, --help show this help message and exit
--description DESCRIPTION
"There is a bit of an air of mystery around this project..."
-r ROOT_URL, --root-url ROOT_URL
-
-a AUTHOR, --author AUTHOR
-
-l LICENSE, --license LICENSE
'mit'
--description-file DESCRIPTION_FILE
'README.md'
-k KEYWORDS, --keywords KEYWORDS
-
--install-requires INSTALL_REQUIRES
-
--include-pip-install-instruction-in-readme
True
-v, --verbose True
-o OVERWRITE, --overwrite OVERWRITE
()
--defaults-from DEFAULTS_FROM
-
```
Note that by default, populate will not overwrite files that all already there.
It will edit the `setup.cfg` file if it's present (and missing some entries).
## Configuring the defaults of `populate`
Note that `defaults-from` option in the `populate` help.
That's probably the most convenient argument of all.
Go check out a file named `wads_configs.json` in the root directory of the project.
(If you don't know how to find that file, try this command:
`python -c "import wads; print(wads)"` to get a clue).
That `wads_configs.json` file contains key-value entries that are used in the wads package.
The `"populate_dflts"` key is used by the populate script.
If you edit that, you'll get different defaults out of the box.
Note that an even better way than editing the existing `wads_configs.json` file is
to write your own configs file, calling it what you want and putting it where you want,
and just adding a `WADS_CONFIGS_FILE` environment variable pointing to it.
(Gotcha: Note the plural on `CONFIGS`).
But you can also add your own key-value pairs if you work on different kinds of projects that need different kinds of defaults.
For your convenience we added a `"custom_dflts_example_you_should_change"` key to illustrate this.
## pack
The typical sequence of the methodical and paranoid could be something like this:
```
python pack.py current-configs # see what you got
python pack.py increment-configs-version # update (increment the version and write that in setup.cfg
python pack.py current-configs-version # see that it worked
python pack.py current-configs # ... if you really want to see the whole configs again (you're really paranoid)
python pack.py run-setup # see that it worked
python pack.py twine-upload-dist # publish
# and then go check things work...
```
If you're are great boilerplate hater you could just do:
```
pack go PKG_DIR
```
(or `pack go --version 0.0.0 PKG_DIR` if it's the very first release).
But we suggest you get familiar with what the steps are doing, so you can bend them to your liking.
# Migration Tools
**New in wads!** Tools to migrate old setuptools projects to modern pyproject.toml format.
Many existing projects still use the old `setup.cfg` format and outdated CI scripts. The `wads.migration` module provides automated tools to migrate these to modern standards:
## Quick Start
```python
from wads.migration import migrate_setuptools_to_hatching, migrate_github_ci_old_to_new
# Migrate setup.cfg to pyproject.toml
pyproject_content = migrate_setuptools_to_hatching('path/to/setup.cfg')
with open('pyproject.toml', 'w') as f:
f.write(pyproject_content)
# Migrate old CI to new format
new_ci = migrate_github_ci_old_to_new('.github/workflows/ci.yml')
with open('.github/workflows/ci_new.yml', 'w') as f:
f.write(new_ci)
```
## What Gets Migrated
- **setup.cfg → pyproject.toml**: All metadata, dependencies, optional dependencies, entry points
- **Old CI → Modern CI**: Updated actions, ruff linting/formatting, modern Python practices
## Documentation
For complete documentation, examples, and API reference, see **[MIGRATION.md](MIGRATION.md)**
Key features:
- ✅ Flexible input formats (file, string, dict)
- ✅ Extensible rule-based transformation system
- ✅ Strict validation - no information loss
- ✅ Default values for missing fields
- ✅ Custom transformation rules
# Troubleshooting
## Vesion tag misalignment
Sometimes the twine PYPI publishing may fail with such a message:
```
WARNING Skipping PKGNAME-0.1.4-py3-none-any.whl because it appears to already exist
WARNING Skipping PKGNAME-0.1.4.tar.gz because it appears to already exist
```
This often means that your git tags are misaligned with the `setup.cfg` version.
You can see your git tags here: `https://github.com/ORG/REPO/tags`.
To repair, do this:
* go to the https://pypi.org/project/ project page and note the VERSION number
* enter a VERSION number ABOVE that one in the version key of `setup.cfg`
* `git tag VERSION`
* `git push origin VERSION`
Raw data
{
"_id": null,
"home_page": "https://github.com/i2mint/wads",
"name": "wads",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "documentation, packaging, publishing",
"author": "Thor Whalen",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/35/7a/64471695d2d275c85404996124685ca0ae36773b8d66186907b9f896ceaa/wads-0.1.47.tar.gz",
"platform": "any",
"description": "# wads\n\nTools for packaging and publishing to pypi for those who just don't want to deal with it\n\nTo install (for example):\n```\npip install wads\n```\n\n# Table of Contents\n\n- [Usage Examples](#usage-examples)\n - [populate](#populate)\n - [pack](#pack)\n- [Migration Tools](#migration-tools) - **NEW!** Migrate old projects to modern format\n- [Troubleshooting](#troubleshooting)\n\n# Usage Examples\n\nWe're going to assume you pointed \"pack\" to \"wads/pack.py\" and \"populate\" to \"wads/populate.py\",\nbecause it's convenient for us to do so. You can achieve this in various ways\n(for example, putting the contents:\n`python /Users/Thor.Whalen/Dropbox/dev/p3/proj/i/wads/wads/pack.py \"$@\"`\nin a file named \"pack\" contained in your OS's script path.)\n\n\n## populate\n\nWhen? When you got a new project and you want to quickly set it up with the packaging goodies.\n\nBasic usage:\n\n```\npopulate PKG_DIR\n```\n\nor, assuming you're using the terminal and you're in the `PKG_DIR` root folder of the project, you can just do:\n\n```\npopulate .\n```\n\nWhat that will do is create and populate some files for you.\nNamely, it will ensure your package directory has the following files (if not present already)\n```\n./LICENSE\n./setup.cfg\n./PKG_NAME/__init__.py\n./README.md\n```\n\nThe `PKG_NAME` will be taken to be the same as the name of the `PKG_DIR`.\n\nThat will work, it will be minimal and will choose defaults for you.\nYou can overwrite many of these, of course.\nFor example,\n\n```\npopulate -r https:///github.com/i2mint --description \"Something about my project...\"\n```\n\nHere are the following options:\n\n```\npositional arguments:\n pkg-dir -\n\noptional arguments:\n -h, --help show this help message and exit\n --description DESCRIPTION\n \"There is a bit of an air of mystery around this project...\"\n -r ROOT_URL, --root-url ROOT_URL\n -\n -a AUTHOR, --author AUTHOR\n -\n -l LICENSE, --license LICENSE\n 'mit'\n --description-file DESCRIPTION_FILE\n 'README.md'\n -k KEYWORDS, --keywords KEYWORDS\n -\n --install-requires INSTALL_REQUIRES\n -\n --include-pip-install-instruction-in-readme\n True\n -v, --verbose True\n -o OVERWRITE, --overwrite OVERWRITE\n ()\n --defaults-from DEFAULTS_FROM\n -\n```\n\nNote that by default, populate will not overwrite files that all already there.\nIt will edit the `setup.cfg` file if it's present (and missing some entries).\n\n## Configuring the defaults of `populate`\n\nNote that `defaults-from` option in the `populate` help.\nThat's probably the most convenient argument of all.\nGo check out a file named `wads_configs.json` in the root directory of the project.\n(If you don't know how to find that file, try this command:\n`python -c \"import wads; print(wads)\"` to get a clue).\n\nThat `wads_configs.json` file contains key-value entries that are used in the wads package.\nThe `\"populate_dflts\"` key is used by the populate script.\nIf you edit that, you'll get different defaults out of the box.\n\nNote that an even better way than editing the existing `wads_configs.json` file is \nto write your own configs file, calling it what you want and putting it where you want, \nand just adding a `WADS_CONFIGS_FILE` environment variable pointing to it. \n(Gotcha: Note the plural on `CONFIGS`).\n\nBut you can also add your own key-value pairs if you work on different kinds of projects that need different kinds of defaults.\nFor your convenience we added a `\"custom_dflts_example_you_should_change\"` key to illustrate this.\n\n## pack\n\nThe typical sequence of the methodical and paranoid could be something like this:\n\n```\npython pack.py current-configs # see what you got\npython pack.py increment-configs-version # update (increment the version and write that in setup.cfg\npython pack.py current-configs-version # see that it worked\npython pack.py current-configs # ... if you really want to see the whole configs again (you're really paranoid)\npython pack.py run-setup # see that it worked\npython pack.py twine-upload-dist # publish\n# and then go check things work...\n```\n\n\nIf you're are great boilerplate hater you could just do:\n\n```\npack go PKG_DIR\n```\n\n(or `pack go --version 0.0.0 PKG_DIR` if it's the very first release).\n\nBut we suggest you get familiar with what the steps are doing, so you can bend them to your liking.\n\n# Migration Tools\n\n**New in wads!** Tools to migrate old setuptools projects to modern pyproject.toml format.\n\nMany existing projects still use the old `setup.cfg` format and outdated CI scripts. The `wads.migration` module provides automated tools to migrate these to modern standards:\n\n## Quick Start\n\n```python\nfrom wads.migration import migrate_setuptools_to_hatching, migrate_github_ci_old_to_new\n\n# Migrate setup.cfg to pyproject.toml\npyproject_content = migrate_setuptools_to_hatching('path/to/setup.cfg')\nwith open('pyproject.toml', 'w') as f:\n f.write(pyproject_content)\n\n# Migrate old CI to new format \nnew_ci = migrate_github_ci_old_to_new('.github/workflows/ci.yml')\nwith open('.github/workflows/ci_new.yml', 'w') as f:\n f.write(new_ci)\n```\n\n## What Gets Migrated\n\n- **setup.cfg \u2192 pyproject.toml**: All metadata, dependencies, optional dependencies, entry points\n- **Old CI \u2192 Modern CI**: Updated actions, ruff linting/formatting, modern Python practices\n\n## Documentation\n\nFor complete documentation, examples, and API reference, see **[MIGRATION.md](MIGRATION.md)**\n\nKey features:\n- \u2705 Flexible input formats (file, string, dict)\n- \u2705 Extensible rule-based transformation system\n- \u2705 Strict validation - no information loss\n- \u2705 Default values for missing fields\n- \u2705 Custom transformation rules\n\n# Troubleshooting\n\n## Vesion tag misalignment\n\nSometimes the twine PYPI publishing may fail with such a message:\n\n```\nWARNING Skipping PKGNAME-0.1.4-py3-none-any.whl because it appears to already exist \nWARNING Skipping PKGNAME-0.1.4.tar.gz because it appears to already exist\n```\n\nThis often means that your git tags are misaligned with the `setup.cfg` version. \nYou can see your git tags here: `https://github.com/ORG/REPO/tags`.\n\nTo repair, do this:\n\n* go to the https://pypi.org/project/ project page and note the VERSION number\n* enter a VERSION number ABOVE that one in the version key of `setup.cfg`\n* `git tag VERSION`\n* `git push origin VERSION`\n",
"bugtrack_url": null,
"license": "Apache Software License",
"summary": "Tools for packaging and publishing to pypi for those who just do not want to deal with it",
"version": "0.1.47",
"project_urls": {
"Homepage": "https://github.com/i2mint/wads"
},
"split_keywords": [
"documentation",
" packaging",
" publishing"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "575f47ac7a239f4edcbebf4f1714dc2894a13fc335bf72f34ae401015a15bcc3",
"md5": "be1e1cf3cc547369a5fe08feabdf2d07",
"sha256": "464f98b9081145e808c24a1818b10c7c5239a864bad842dbdae0fc538caef19a"
},
"downloads": -1,
"filename": "wads-0.1.47-py3-none-any.whl",
"has_sig": false,
"md5_digest": "be1e1cf3cc547369a5fe08feabdf2d07",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 131079,
"upload_time": "2025-11-14T02:02:53",
"upload_time_iso_8601": "2025-11-14T02:02:53.769184Z",
"url": "https://files.pythonhosted.org/packages/57/5f/47ac7a239f4edcbebf4f1714dc2894a13fc335bf72f34ae401015a15bcc3/wads-0.1.47-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "357a64471695d2d275c85404996124685ca0ae36773b8d66186907b9f896ceaa",
"md5": "7df8fa28fe78857d495da395ce789786",
"sha256": "5ccbacbbaeb77e4a02a033179384e4d0f6c06278456f8513ee796a9f9e4a5640"
},
"downloads": -1,
"filename": "wads-0.1.47.tar.gz",
"has_sig": false,
"md5_digest": "7df8fa28fe78857d495da395ce789786",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 124187,
"upload_time": "2025-11-14T02:02:55",
"upload_time_iso_8601": "2025-11-14T02:02:55.124290Z",
"url": "https://files.pythonhosted.org/packages/35/7a/64471695d2d275c85404996124685ca0ae36773b8d66186907b9f896ceaa/wads-0.1.47.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-11-14 02:02:55",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "i2mint",
"github_project": "wads",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "wads"
}
JSON
