Update readme a little

This commit is contained in:
grym 2022-11-23 13:37:46 -05:00
parent 68fd631a00
commit f0fda7a5c3
1 changed files with 59 additions and 0 deletions

View File

@ -2,3 +2,62 @@
This is the minimum working example that I know of for a python package
structure post-PEP517/8 and with pip/setuptools now allowing editable installs
without a setup.py.
* Motivation
Python packaging can get very complicated. Sometimes it's easier to just have
a working example you can copy from.
Do you have one or more python files that you've written and would sure like to
use, but also find that:
- "It works" in your IDE but when you run python elsewhere you get
=ModuleNotFound= errors?
- Someone has told you that your code "should be a package" so that "i can pip
install it"?
and you're at loose ends about what to do next?
This worked example of a repo might help.
* TL;DR
- Put package information, build information, and entry points in =pyproject.toml=
- You can now install (and in editable mode even!) your code and its python
dependencies with pip.
- You can make CLI entry points that act like normal programs
- You can share your code with others, or include it as a dependency in other projects.
-
* So what are these files?
** convenience boilerplate
#+begin_src
.gitignore
Makefile
.pre-commit-config.yaml
README.org
#+end_src
These files are optional.
Using the lovely [[https://gitignore.io][gitignore.io]] collection of recommended ignores, I've populated
a =.gitignore= for python and common editors.
If you like to automate the creation of venvs and installation and whatnot with
=make=, as I do, then the included =Makefile= may be useful.
Automatic code formatting with =black= and =isort= can be accomplished with =.pre-commit-config.yaml=
if [[https://pre-commit.com][pre-commit]] is used.
And this file is =Readme.org=; choose a markup language of your preference.
** package files
#+begin_src
├── pyproject.toml
├── template
│   ├── cli.py
│   └── __init__.py
#+end_src
=pyproject.toml= specifies everything =pip= needs to install a package,
including its name and metadata, what dependencies it requires, what entry
points to create, what extras may be available, and how it should be built.
This information has historically (and may still be, if you like) spread across
some combination of ={pyproject.toml, setup.cfg, setup.py}=. Following
adoption of PEP517/517 by =setuptools=, though, you can ram it all into
=pyproject.toml=.
=template/= is the directory of the python package. The name of the package is
=template=, it has two modules =__init__= and =cli=, and =cli= has one function
=main=, which is configured as the entry point, and simply prints ="Hello, world!"=.