Update readme a little
This commit is contained in:
parent
68fd631a00
commit
f0fda7a5c3
59
README.org
59
README.org
|
@ -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!"=.
|
||||
|
|
Loading…
Reference in New Issue