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. :)