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&for
mat=json&token=3oh45c20f97769b9c0f30d3&user=8...
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 ch...
Live Demo!
Documentation is Important
● If you like Sphinx or
reStructuredText,
great.
● I don’t.
○ A bit large
○ A bit complicated,
...
Pycco - lightweight, markdown docs
Pycco - lightweight, markdown docs
$ pip install pycco
$ pycco src/my_python_file.py
pycco = mypython.py -> docs/my_python...
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...
https://www.destroyallsoftware.com/talks/wat
What is a “package,” actually?
● Python Module:
○ Any single .py file.
○ Or, a multi-file module, which puts many .py file...
What is a “package,” actually?
● Python Package:
○ Often people use this word to describe a multi-file
module.
○ It's also...
What is a “package,” actually?
● Python Distribution:
○ "a versioned archive file that contains Python
packages, modules, ...
Why not the Python Distribution
Index?
My “Official” Packaging Docs
● 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)

●
●
●
●
●...
My “Official” Packaging Docs
● MANIFEST.in
○ The distributionmaking utilities
include some files by
default, but not all.
...
My Packaging Docs - setup.py
● You will use a
utility to:
○ “Package up” your
package's files
○ Register your
project with...
My Packaging Docs - setup.py
● setup.py provides
that utility the info
it needs to
“package up” the
distribution and
submi...
More “Wat” to setup.py...
● Too many utilities!
○ Distutils,
Setuptools,
Distribute,
Distutils2

● Different
limitations!
...
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. :)
Is it a Package or a Wrapper? Designing, Documenting, and Distributing a Python Helper Library for the Cicero API
Is it a Package or a Wrapper? Designing, Documenting, and Distributing a Python Helper Library for the Cicero API
Upcoming SlideShare
Loading in...5
×

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

339

Published on

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.

Published in: Technology
0 Comments
1 Like
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total Views
339
On Slideshare
0
From Embeds
0
Number of Embeds
1
Actions
Shares
0
Downloads
1
Comments
0
Likes
1
Embeds 0
No embeds

No notes for slide

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

  1. 1. Is it a Package or a Wrapper? Designing, Documenting, and Distributing a Helper Library for the Cicero API
  2. 2. advanced spatial analysis on the web • • • • • UI/UX Design Web/Mobile Data Science HPC R&D
  3. 3. https://cicero.azavea.com/v3.1/official? last_name=Obama&valid_range=ALL&for mat=json&token=3oh45c20f97769b9c0f30d3&user=851&pretty= 1
  4. 4. So that’s an API...What’s a Wrapper?
  5. 5. 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.
  6. 6. Live Demo!
  7. 7. 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
  8. 8. Pycco - lightweight, markdown docs
  9. 9. Pycco - lightweight, markdown docs $ pip install pycco $ pycco src/my_python_file.py pycco = mypython.py -> docs/my_python_file.html
  10. 10. Pycco - lightweight, markdown docs
  11. 11. Pycco
  12. 12. Packaging and Submitting to PyPi! $ pip install whatever-python-library-you-want
  13. 13. “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
  14. 14. https://www.destroyallsoftware.com/talks/wat
  15. 15. 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
  16. 16. 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.
  17. 17. 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.
  18. 18. Why not the Python Distribution Index?
  19. 19. My “Official” Packaging Docs ● Your Modules multi-file (__init__. py) or not
  20. 20. 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
  21. 21. 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.
  22. 22. 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.
  23. 23. 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
  24. 24. More “Wat” to setup.py... ● Too many utilities! ○ Distutils, Setuptools, Distribute, Distutils2 ● Different limitations! ● No guidance! ● More “wat”! ● When in doubt, use Setuptools.
  25. 25. Finally, Ready to Upload! $ python setup.py register -r pypi $ python setup.py sdist upload -r pypi
  26. 26. Come and get it https://pypi.python.org/pypi/python-cicero/0.1.0 $ pip install python-cicero
  27. 27. Is it a Package or a Wrapper? Both. Also a distribution. :)
  1. A particular slide catching your eye?

    Clipping is a handy way to collect important slides you want to go back to later.

×