initial release

HISTORY.rst

@@ -3,7 +3,7 @@
 History
 -------
 
-0.1.0 (2015-01-01)
+0.1.0 (2014-12-21)
 ---------------------
 
 * First release on PyPI.

Makefile

@@ -16,9 +16,10 @@ help:
 clean: clean-build clean-pyc clean-test
 
 clean-build:
-	rm -fr build/
-	rm -fr dist/
-	rm -fr *.egg-info
+	rm -rf build/
+	rm -rf dist/
+	rm -rf *.egg-info
+	rm -rf htmlcov/
 
 clean-pyc:
 	find . -name '*.pyc' -exec rm -f {} +

README.rst

@@ -15,9 +15,94 @@ swapi-python
 A Python helper library for swapi.co - the Star Wars API
 
 * Free software: BSD license
-* Documentation: https://swapi-python.readthedocs.org.
+* Documentation: https://swapi.readthedocs.org.
 
-Features
---------
+============
+Installation
+============
 
-* TODO
+At the command line::
+
+    $ pip install swapi
+
+Basic Usage
+========
+
+To use swapi-python in a project::
+
+    import swapi
+
+All resources are accessible through the top-level ``get_resource()`` methods::
+
+    luke = swapi.get_person(1)
+    tatooine = swapi.get_planet(1)
+
+Methods
+=======
+
+These are the top-level methods you can use to get resources from swapi.co. To learn more about the models and objects that are returned, see the ``models`` page.
+
+get_person(id)
+------------
+
+Return a single ``Person`` resource.
+
+Example::
+
+    swapi.get_person(1)
+    >>> <Person - Luke Skywalker>
+
+
+get_planet(id)
+------------
+
+Return a single ``Planet`` resource.
+
+Example::
+
+    swapi.get_planet(1)
+    >>> <Planet - Tatooine>
+
+
+get_starship(id)
+------------
+
+Return a single ``Starship`` resource.
+
+Example::
+
+    swapi.get_starship(6)
+    >>> <Starship - Death Star>
+
+
+get_vehicle(id)
+------------
+
+Return a single ``Vehicle`` resource.
+
+Example::
+
+    swapi.get_vehicle(4)
+    >>> <Vehicle - Sand Crawler>
+
+
+get_film(id)
+------------
+
+Return a single ``Film`` resource.
+
+Example::
+
+    swapi.get_planet(1)
+    >>> <Planet - A New Hope>
+
+
+get_all("resource")
+------------
+
+Return a ``QuerySet`` containing all the items in a single resource. See the ```models``` page for more information on the models used in swapi-python.
+
+Example::
+
+    swapi.get_all("films")
+    >>> <FilmQuerySet - 6>

docs/conf.py

@@ -15,6 +15,7 @@
 
 import sys
 import os
+RTD_NEW_THEME = True
 
 # If extensions (or modules to document with autodoc) are in another
 # directory, add these directories to sys.path here. If the directory is
@@ -31,7 +32,7 @@
 # version is used.
 sys.path.insert(0, project_root)
 
-import swapi-python
+import swapi
 
 # -- General configuration ---------------------------------------------
 
@@ -63,9 +64,9 @@
 # the built documents.
 #
 # The short X.Y version.
-version = swapi-python.__version__
+version = swapi.__version__
 # The full version, including alpha/beta/rc tags.
-release = swapi-python.__version__
+release = swapi.__version__
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/index.rst

@@ -14,6 +14,7 @@ Contents:
    readme
    installation
    usage
+   models
    contributing
    authors
    history

docs/models.rst

@@ -0,0 +1,148 @@
+====
+Models
+====
+
+Swapi-python uses custom models to handle single resources and collections of resources in a native and pythonic way.
+
+This page documents the extra methods and functions of those classes.
+
+
+Single Resource Model
+=====================
+
+A single resource model maps all the standard attributes for a resource as properties on the object. For example, a ``People`` resource has a ``name`` and ``height`` attribute. These can be accessed with swapi-python as properties, like so::
+
+    luke = swapi.get_person(1)
+    luke.name
+    >>> u'Luke Skywalker'
+    luke.height
+    >>> u'172'
+
+
+Getting Related Resources
+-------------------------
+
+Each resource model has specific methods for getting back the collection of resources related to it. For example, the People resource can have Starship Resources linked to it. With swapi-python you can get those resources like so::
+
+    luke = swapi.get_person(1)
+    ships = luke.get_starships()
+
+Each resource model has slightly different methods. Multiple resources return a Multiple Collection Model (see below).
+
+People
+------
+* ``get_starships()``
+Return the starships that this person has piloted.
+
+* ``get_vehicles()``
+Return the vehicles that this person has piloted.
+
+* ``get_homeworld()``
+Get the homeworld of this person.
+
+* ``get_species()``
+Return the species of this person.
+
+* ``get_films()``
+Return the films that this person has been in.
+
+Species
+-------
+* ``get_films()``
+Return the films that this species has been in.
+
+* ``get_people()``
+Return the people who are a member of this species.
+
+* ``get_homeworld()``
+Return the homeworld of this species.
+
+Planet
+-------
+* ``get_residents()``
+Return the people who live on this planet.
+
+* ``get_films()``
+Return the films that this planet has appeared in.
+
+Starship
+--------
+* ``get_pilots()``
+Return the pilots of this starship.
+
+* ``get_films()``
+Return the films that this starship has been in.
+
+Vehicle
+-------
+* ``get_pilots()``
+Return the pilots of this vehicle.
+
+* ``get_films()``
+Return the films that this vehicle has been in.
+
+Film
+----
+* ``get_starships()``
+Get the starships in this film.
+
+* ``get_characters()``
+Get the characters in this film.
+
+* ``get_vehicles()``
+Get the vehicles in this film.
+
+* ``get_planets()``
+Get the planets in this film.
+
+* ``get_species()``
+Get the species in this film.
+
+* ``gen_opening_crawl()``
+A generator yielding each line of the opening crawl for this film.
+
+* ``print_crawl()``
+A novelty method that prints out each line of the opening crawl with a 0.5 second delay between each line.
+
+
+Multiple Collection Model
+=========================
+
+When you query swapi.co for multiple resources of the same type, they will be returned as a ``ResourceQuerySet``, which is a collection of those resources that you requested. For example, to get the ``Starship`` resources linked to a person, you can do the following::
+
+    luke = swapi.get_person(1)
+    starships = luke.get_starships()
+    >>> <StarshipQuerySet - 2>
+
+``ResourceQuerySet`` models have additional methods for dealing with multiple resources.
+
+The items are accessible as the ``item`` property on the ResourceQuerySet if you want to directly access them::
+
+    starships.items
+    >>> [<Starship - X-wing>, <Starship - Lambda Shuttle>]
+
+.order_by("attribute")
+----------------------
+
+Return the list of Single Resource Models in this collection, ordered by a particular attribute. For example::
+
+    planets = swapi.get_all("planets")
+    for p in planets.order_by("diameter"):
+        print(p.name)
+
+This will return the planets ordered by their diameter.
+
+This method will try to turn the attribute into an interger before ordering them, as most resources are unicode strings. If you try to order by string, it will order it alphabetically. Please be aware that for string ordering it might not always come out as you would expect.
+
+.count()
+-------
+
+Return a count of the number of items in this collection..
+
+.iter()
+-------
+
+An iterable method that can be used to iterate over each item in this collection::
+
+    for v in vehicles.iter():
+        print(v.name)

docs/modules.rst

@@ -0,0 +1,7 @@
+swapi
+=====
+
+.. toctree::
+   :maxdepth: 4
+
+   swapi

docs/swapi.rst

@@ -0,0 +1,54 @@
+swapi package
+=============
+
+Submodules
+----------
+
+swapi.exceptions module
+-----------------------
+
+.. automodule:: swapi.exceptions
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+swapi.models module
+-------------------
+
+.. automodule:: swapi.models
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+swapi.settings module
+---------------------
+
+.. automodule:: swapi.settings
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+swapi.swapi module
+------------------
+
+.. automodule:: swapi.swapi
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+swapi.utils module
+------------------
+
+.. automodule:: swapi.utils
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+Module contents
+---------------
+
+.. automodule:: swapi
+    :members:
+    :undoc-members:
+    :show-inheritance: