Is it a Package or a Wrapper? Designing, Documenting, and Distributing a Python Helper Library for...
-
Upload
azavea -
Category
Technology
-
view
319 -
download
2
description
Transcript of Is it a Package or a Wrapper? Designing, Documenting, and Distributing a Python Helper Library for...
Is it a Package or a Wrapper?
Designing, Documenting, and Distributing a Helper Library for the Cicero API
advanced
spatial analysis
on the web
• UI/UX Design
• Web/Mobile
• Data Science
• HPC
• R&D
https://cicero.azavea.com/v3.1/official?last_name=Obama&valid_range=ALL&format=json&token=3oh-45c20f97769b9c0f30d3&user=851&pretty=1
So that’s an API...What’s a Wrapper?
So that’s an API...What’s a Wrapper?
● Reese’s cups, like APIs, are filled with awesome. Data! Peanut Butter!
● But the chocolate, like JSON and XML and HTTP, will melt all over your fingers. It’s messy.
● The wrapper keeps your hands clean so you don’t have to deal with the messy stuff.
● You just program in Python.
Live Demo!
Documentation is Important
● If you like Sphinx or reStructuredText, great.
● I don’t.○ A bit large○ A bit complicated,
build process, etc○ Markdown is more
intuitive, to me● Make docs, not
arguments
Pycco - lightweight, markdown docs
Pycco - lightweight, markdown docs
$ pip install pycco
$ pycco src/my_python_file.pypycco = mypython.py -> docs/my_python_file.html
Pycco - lightweight, markdown docs
Pycco
Packaging and Submitting to PyPi!
$ pip install whatever-python-library-you-want
“The “Python Packaging User Guide” (PUG) aims to be the authoritative resource on how to package and install distributions in Python using current tools...”
https://python-packaging-user-guide.readthedocs.org/en/latest/index.html
https://www.destroyallsoftware.com/talks/wat
● Python Module:○ Any single .py file.○ Or, a multi-file module, which puts many .py files in a
directory with an __init__.py, which■ Tells Python to treat that whole directory as one
module.
○ module■ __init__.py■ file1.py■ file2.py
What is a “package,” actually?
● Python Package:○ Often people use this word to describe a multi-file
module.○ It's also a synonym for "distribution".○ And it's also something in between the two.○ And a verb.
What is a “package,” actually?
● Python Distribution:○ "a versioned archive file that contains Python
packages, modules, and other resource files... The distribution file is what an end-user will download from the internet and install."
● Distributed to your users with pip and the Python Package Index.
● But you rarely come across this word.
What is a “package,” actually?
Why not the Python Distribution Index?
● Your Modules - multi-file (__init__.py) or not
My “Official” Packaging Docs
● Our “root” package○ (Yes, a package -
more than a module, not yet a distribution)
● docs● cicero_examples.py● CHANGES.txt● LICENSE.txt● README.rst● MANIFEST.in● setup.py
My “Official” Packaging Docs
● MANIFEST.in○ The distribution-
making utilities include some files by default, but not all.■ Like our docs! We
want to distribute those too!
● The manifest file describes what else to include.
My “Official” Packaging Docs
● You will use a utility to:○ “Package up” your
package's files○ Register your
project with PyPi○ Upload an archived
distribution file for others to download.
My Packaging Docs - setup.py
● setup.py provides that utility the info it needs to “package up” the distribution and submit it to PyPi.○ name, version, url,
description, classifiers, etc
My Packaging Docs - setup.py
● Too many utilities!○ Distutils,
Setuptools, Distribute, Distutils2
● Different limitations!
● No guidance!● More “wat”! ● When in doubt,
use Setuptools.
More “Wat” to setup.py...
Finally, Ready to Upload!
$ python setup.py register -r pypi$ python setup.py sdist upload -r pypi
Come and get it
https://pypi.python.org/pypi/python-cicero/0.1.0$ pip install python-cicero
Is it a Package or a Wrapper?
Both.Also a distribution. :)