Andrew Thompson delivered this talk at the January 2014 joint meeting of the PhillyPUG Python User's Group and the GeoPhilly GIS Meetup group. Topics covered include Rest APIs, API wrappers, Python documentation tools, and Python module packaging practices and the Python Package Index.

1. Is it a Package or
a Wrapper?
Designing, Documenting, and Distributing
a Helper Library for the Cicero API

2. advanced
spatial analysis
on the web
•
•
•
•
•
UI/UX Design
Web/Mobile
Data Science
HPC
R&D

5. https://cicero.azavea.com/v3.1/official?
last_name=Obama&valid_range=ALL&for
mat=json&token=3oh45c20f97769b9c0f30d3&user=851&pretty=
1

6. So that’s an API...What’s a Wrapper?

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

8. Live Demo!

9. 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

10. Pycco - lightweight, markdown docs

11. Pycco - lightweight, markdown docs
$ pip install pycco
$ pycco src/my_python_file.py
pycco = mypython.py -> docs/my_python_file.html

12. Pycco - lightweight, markdown docs

13. Pycco

14. Packaging and Submitting to PyPi!
$ pip install whatever-python-library-you-want

15. “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

16. https://www.destroyallsoftware.com/talks/wat

17. What is a “package,” actually?
● 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

18. 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.

19. 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.

20. Why not the Python Distribution
Index?

21. My “Official” Packaging Docs
● Your Modules multi-file (__init__.
py) or not

22. 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

23. My “Official” Packaging Docs
● MANIFEST.in
○ The distributionmaking 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.

24. My Packaging Docs - setup.py
● 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.

25. 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

26. More “Wat” to setup.py...
● Too many utilities!
○ Distutils,
Setuptools,
Distribute,
Distutils2
● Different
limitations!
● No guidance!
● More “wat”!
● When in doubt,
use Setuptools.

27. Finally, Ready to Upload!
$ python setup.py register -r pypi
$ python setup.py sdist upload -r pypi

28. Come and get it
https://pypi.python.org/pypi/python-cicero/0.1.0
$ pip install python-cicero

29. Is it a Package or a Wrapper?
Both.
Also a distribution. :)