Move swagger module to ext.marshmallow; update docs

marshmallow no longer a hard dependency

CHANGELOG.rst

@@ -4,7 +4,7 @@ Changelog
 0.3.0 (unreleased)
 ++++++++++++++++++
 
-* Rename project to apispec.
+* Rename and repackage as "apispec".
 * Support ``enum`` field of JSON Schema based on ``OneOf`` and ``ContainsOnly`` validators.
 
 0.2.0 (2015-09-27)

CONTRIBUTING.rst

@@ -32,6 +32,7 @@ Setting Up for Local Development
 
     # After activating your virtualenv
     $ pip install -r dev-requirements.txt
+    $ npm install -g swagger-tools
 
 3. Install apispec in develop mode. ::
 
@@ -47,7 +48,7 @@ apispec abides by the following branching model:
     Current development branch. **New features should branch off here**.
 
 ``pypi``
-    Current production release on PyPI.
+    Latest PyPI release.
 
 ``X.Y-line``
     Maintenance branch for release ``X.Y``. **Bug fixes should be sent to the most recent release branch.**. The maintainer will forward-port the fix to ``dev``. Note: exceptions may be made for bug fixes that introduce large code changes.

README.rst

@@ -86,6 +86,7 @@ Generated Swagger spec
     #   "paths": {
     #     "/random": {
     #       "get": {
+    #         "description": "A cute furry animal endpoint."
     #         "responses": {
     #           "200": {
     #             "schema": {
@@ -94,7 +95,6 @@ Generated Swagger spec
     #             "description": "A pet to be returned"
     #           }
     #         },
-    #         "description": "A cute furry animal endpoint."
     #       }
     #     }
     #   },

apispec/__init__.py

@@ -1,4 +1,6 @@
 # -*- coding: utf-8 -*-
+"""Contains the main `APISpec` class.
+"""
 
 __version__ = '0.3.0'
 __author__ = 'Steven Loria'

apispec/compat.py

@@ -0,0 +1,23 @@
+# -*- coding: utf-8 -*-
+import sys
+
+PY2 = int(sys.version[0]) == 2
+
+if PY2:
+    text_type = unicode
+    binary_type = str
+    string_types = (str, unicode)
+    unicode = unicode
+    basestring = basestring
+    iterkeys = lambda d: d.iterkeys()
+    itervalues = lambda d: d.itervalues()
+    iteritems = lambda d: d.iteritems()
+else:
+    text_type = str
+    binary_type = bytes
+    string_types = (str,)
+    unicode = str
+    basestring = (str, bytes)
+    iterkeys = lambda d: d.keys()
+    itervalues = lambda d: d.values()
+    iteritems = lambda d: d.items()

apispec/core.py

@@ -1,8 +1,8 @@
 # -*- coding: utf-8 -*-
-
+"""Core apispec classes and functions."""
 import re
 
-from marshmallow.compat import iterkeys
+from apispec.compat import iterkeys
 from .exceptions import APISpecError, PluginError
 
 VALID_METHODS = [
@@ -74,7 +74,7 @@ class APISpec(object):
 
     :param str title: API title
     :param str version: API version
-    :param tuple plugins: Paths to plugin modules
+    :param tuple plugins: Import paths to plugins.
     :param dict info: Optional dict to add to `info`
         See https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#infoObject
     :param **dict options: Optional top-level keys

apispec/ext/flask.py

@@ -7,7 +7,7 @@
 
 from flask import current_app
 
-from marshmallow.compat import iteritems
+from apispec.compat import iteritems
 from apispec import Path
 from apispec.exceptions import APISpecError
 from apispec import utils
@@ -29,14 +29,20 @@ def _rule_for_view(view):
 RE_URL = re.compile(r'<(?:[^:<>]+:)?([^<>]+)>')
 
 def flaskpath2swagger(path):
+    """Convert a Flask URL rule to a Swagger-compliant path.
+
+    :param str path: Flask path template.
+    """
     return RE_URL.sub(r'{\1}', path)
 
 def path_from_view(spec, view, operations, **kwargs):
+    """Path helper that allows passing a Flask view function."""
     rule = _rule_for_view(view)
     path = flaskpath2swagger(rule.rule)
     operations = utils.load_operations_from_docstring(view.__doc__)
     path = Path(path=path, operations=operations)
     return path
 
 def setup(spec):
+    """Setup for the plugin."""
     spec.register_path_helper(path_from_view)

apispec/ext/marshmallow.py → apispec/ext/marshmallow/__init__.py

@@ -1,11 +1,17 @@
 # -*- coding: utf-8 -*-
+"""Marshmallow plugin for apispec. Allows passing a marshmallow
+`Schema` to `APISpec.definition <apispec.APISpec.definition>`
+and `APISpec.add_path <apispec.APISpec.add_path>` (for responses).
+
+Requires marshmallow>=1.2.
+"""
 from __future__ import absolute_import
 
 import marshmallow
 
-from apispec import swagger
 from apispec.core import Path
 from apispec.utils import load_operations_from_docstring
+from . import swagger
 
 NAME = 'apispec.ext.marshmallow'
 
@@ -24,6 +30,9 @@ def schema_definition_helper(spec, name, schema, **kwargs):
     return swagger.schema2jsonschema(schema, spec=spec)
 
 def schema_path_helper(spec, view, **kwargs):
+    """Path helper that allows passing a Schema as a response. Responses can be
+    defined in a view's docstring.
+    """
     operations = (
         load_operations_from_docstring(view.__doc__) or
         kwargs.get('operations')
@@ -54,5 +63,6 @@ def resolve_schema_cls(schema):
     return marshmallow.class_registry.get_class(schema)
 
 def setup(spec):
+    """Setup for the marshmallow plugin."""
     spec.register_definition_helper(schema_definition_helper)
     spec.register_path_helper(schema_path_helper)

apispec/utils.py

@@ -5,8 +5,8 @@
 import subprocess
 
 import yaml
-from marshmallow.compat import iteritems
 
+from apispec.compat import iteritems
 from apispec import exceptions
 
 # from django.contrib.admindocs.utils

dev-requirements.txt

@@ -6,6 +6,7 @@ flake8==2.4.1
 # soft dependencies
 webargs>=0.15.0
 Flask
+marshmallow
 
 # testing
 pytest>=2.8.0

docs/api_core.rst

@@ -0,0 +1,14 @@
+Core API
+========
+
+apispec
+-------
+
+.. automodule:: apispec
+    :members:
+
+apispec.exceptions
+------------------
+
+.. automodule:: apispec.exceptions
+    :members:

docs/api_ext.rst

@@ -0,0 +1,20 @@
+Built-in Extensions
+===================
+
+apispec.ext.marshmallow
+-----------------------
+
+.. automodule:: apispec.ext.marshmallow
+    :members:
+
+apispec.ext.marshmallow.swagger
++++++++++++++++++++++++++++++++
+
+.. automodule:: apispec.ext.marshmallow.swagger
+    :members:
+
+apispec.ext.flask
+-----------------
+
+.. automodule:: apispec.ext.flask
+    :members:

docs/index.rst

@@ -85,6 +85,7 @@ Generated Swagger spec
     #   "paths": {
     #     "/random": {
     #       "get": {
+    #         "description": "A cute furry animal endpoint."
     #         "responses": {
     #           "200": {
     #             "schema": {
@@ -93,7 +94,6 @@ Generated Swagger spec
     #             "description": "A pet to be returned"
     #           }
     #         },
-    #         "description": "A cute furry animal endpoint."
     #       }
     #     }
     #   },
@@ -134,7 +134,8 @@ API Reference
 .. toctree::
     :maxdepth: 2
 
-    api_reference
+    api_core
+    api_ext
 
 Project Links
 =============

setup.cfg

@@ -11,4 +11,4 @@ universal=1
 [flake8]
 ignore = E127,E128,E265,E302
 max-line-length = 100
-exclude=.git,docs,tests,env,venv,.ropeproject,_sandbox
+exclude=.git,docs,tests,apispec/compat.py,env,venv,.ropeproject,_sandbox

setup.py

@@ -4,7 +4,6 @@
 
 
 REQUIRES = [
-    'marshmallow>=1.2.0',
     'PyYAML>=3.10'
 ]
 
@@ -48,7 +47,7 @@ def read(fname):
     install_requires=REQUIRES,
     license=read("LICENSE"),
     zip_safe=False,
-    keywords='apispec marshmallow webargs rest api',
+    keywords='apispec swagger spec rest api',
     classifiers=[
         'Development Status :: 2 - Pre-Alpha',
         'Intended Audience :: Developers',

tests/test_ext_marshmallow.py

@@ -1,7 +1,8 @@
 # -*- coding: utf-8 -*-
 import pytest
 
-from apispec import APISpec, swagger
+from apispec import APISpec
+from apispec.ext.marshmallow import swagger
 from .schemas import PetSchema
 
 @pytest.fixture()

tests/test_swagger.py

@@ -12,9 +12,9 @@
 from marshmallow import fields, Schema, validate
 from marshmallow.compat import binary_type
 
-from apispec import swagger
+from apispec.ext.marshmallow import swagger
 from apispec import exceptions, utils, APISpec
-from apispec.swagger import arg2parameter, arg2property, field2parameter
+from apispec.ext.marshmallow.swagger import arg2parameter, arg2property, field2parameter
 
 if HAS_WEBARGS_ARG:
     class TestArgToSwagger: