tessl/pypi-flask-restplus
Fully featured framework for fast, easy and documented API development with Flask
—
Pending
Quality
Pending
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
api-resources.mddocs/
API and Resources
Core classes for creating RESTful APIs with automatic documentation, routing, and response handling. The Api class serves as the main entry point for Flask-RESTPlus applications, while Resource provides the base class for defining API endpoints.
Capabilities
Api Class
The main class that wraps a Flask application to provide RESTful API functionality with automatic documentation generation.
class Api:
def __init__(self, app=None, version='1.0', title=None, description=None,
terms_url=None, license=None, license_url=None, contact=None,
contact_url=None, contact_email=None, authorizations=None,
security=None, doc='/', default_id=None, default='default',
validate=None, tags=None, prefix='', ordered=False, **kwargs):
"""
Initialize the API.
Args:
app (Flask, optional): Flask application instance
version (str): API version
title (str, optional): API title
description (str, optional): API description
terms_url (str, optional): Terms of service URL
license (str, optional): License name
license_url (str, optional): License URL
contact (str, optional): Contact name
contact_url (str, optional): Contact URL
contact_email (str, optional): Contact email
authorizations (dict, optional): Authorization definitions
security (list, optional): Global security requirements
doc (str): Documentation endpoint path
default_id (callable, optional): Default operation ID generator
default (str): Default namespace name
validate (bool, optional): Enable request validation
tags (list, optional): Global tags
prefix (str): URL prefix for all routes
ordered (bool): Preserve model field ordering
"""
def init_app(self, app, **kwargs):
"""
Initialize the API with a Flask app.
Args:
app (Flask): Flask application instance
**kwargs: Additional configuration options
"""
def add_resource(self, resource, *urls, endpoint=None, **kwargs):
"""
Add a resource to the API.
Args:
resource (Resource): Resource class to add
*urls (str): URL routes for the resource
endpoint (str, optional): Endpoint name
**kwargs: Additional route arguments
Returns:
Resource: The added resource class
"""
def route(self, *urls, **kwargs):
"""
Decorator to add a resource route.
Args:
*urls (str): URL routes
**kwargs: Route arguments
Returns:
callable: Decorator function
"""
def add_namespace(self, ns, path=None):
"""
Add a namespace to the API.
Args:
ns (Namespace): Namespace to add
path (str, optional): URL path prefix
"""
def namespace(self, *args, **kwargs):
"""
Create and return a new namespace.
Args:
*args: Namespace arguments
**kwargs: Namespace keyword arguments
Returns:
Namespace: New namespace instance
"""
def model(self, name=None, model=None, mask=None, strict=False, **kwargs):
"""
Register a model for documentation and validation.
Args:
name (str, optional): Model name
model (dict or Model, optional): Model definition
mask (str, optional): Field mask
strict (bool): Strict validation mode
**kwargs: Model fields
Returns:
Model: Registered model
"""
def clone(self, name, model, **kwargs):
"""
Clone an existing model with modifications.
Args:
name (str): New model name
model (Model): Model to clone
**kwargs: Field modifications
Returns:
Model: Cloned model
"""
def inherit(self, name, *parents, **kwargs):
"""
Create a model inheriting from parent models.
Args:
name (str): New model name
*parents (Model): Parent models
**kwargs: Additional fields
Returns:
Model: Inherited model
"""
def expect(*inputs, validate=None):
"""
Decorator for documenting expected request inputs.
Args:
*inputs: Expected input models or parsers
validate (bool, optional): Enable validation
Returns:
callable: Decorator function
"""
def marshal_with(fields, as_list=False, code=200, description=None, **kwargs):
"""
Decorator for marshalling response data.
Args:
fields (dict or Model): Fields for marshalling
as_list (bool): Marshal as list
code (int): HTTP status code
description (str, optional): Response description
**kwargs: Additional marshal options
Returns:
callable: Decorator function
"""
def marshal_list_with(fields, **kwargs):
"""
Decorator for marshalling list responses.
Args:
fields (dict or Model): Fields for marshalling
**kwargs: Additional marshal options
Returns:
callable: Decorator function
"""
def doc(self, shortcut=None, **kwargs):
"""
Decorator for adding documentation to resources.
Args:
shortcut (str, optional): Documentation shortcut
**kwargs: Documentation parameters
Returns:
callable: Decorator function
"""
def hide(self):
"""
Decorator to hide a resource from documentation.
Returns:
callable: Decorator function
"""
def deprecated(self):
"""
Decorator to mark a resource as deprecated.
Returns:
callable: Decorator function
"""
def header(self, name, description=None, **kwargs):
"""
Decorator for documenting expected headers.
Args:
name (str): Header name
description (str, optional): Header description
**kwargs: Additional header parameters
Returns:
callable: Decorator function
"""
def produces(self, mimetypes):
"""
Decorator for documenting response content types.
Args:
mimetypes (list): Supported MIME types
Returns:
callable: Decorator function
"""
def response(self, code, description, model=None, **kwargs):
"""
Decorator for documenting response schemas.
Args:
code (int): HTTP status code
description (str): Response description
model (Model, optional): Response model
**kwargs: Additional response parameters
Returns:
callable: Decorator function
"""
def errorhandler(self, exception):
"""
Register an error handler.
Args:
exception (Exception): Exception class
Returns:
callable: Decorator function
"""
def owns_endpoint(self, endpoint):
"""
Check if API owns an endpoint.
Args:
endpoint (str): Endpoint name
Returns:
bool: True if owned by this API
"""
def output(self, resource):
"""
Apply output formatting to a resource response.
Args:
resource: Resource response
Returns:
Response: Formatted response
"""
@property
def payload(self):
"""
Get the current request payload.
Returns:
dict: Request payload data
"""
@property
def specs_url(self):
"""
Get the Swagger specification URL.
Returns:
str: Swagger JSON URL
"""
def add_resource(self, resource, *urls, **kwargs):
"""
Add a resource to the API.
Args:
resource: Resource class to add
*urls: URL patterns for the resource
**kwargs: Additional resource options
"""
def make_response(self, data, *args, **kwargs):
"""
Create a Flask response from data.
Args:
data: Response data
*args: Additional arguments
**kwargs: Additional keyword arguments
Returns:
Response: Flask response object
"""
def error_router(self, original_handler, e):
"""
Route errors to appropriate handlers.
Args:
original_handler: Original error handler
e (Exception): Exception to handle
Returns:
Response: Error response
"""
def handle_error(self, e):
"""
Handle API errors.
Args:
e (Exception): Exception to handle
Returns:
Response: Error response
"""
def as_postman(self, urlvars=False, swagger=False):
"""
Generate Postman collection for the API.
Args:
urlvars (bool): Include URL variables
swagger (bool): Use Swagger definitions
Returns:
dict: Postman collection data
"""Resource Class
Base class for API resources that handles HTTP method routing and provides integration with Flask-RESTPlus features.
class Resource:
# Class attributes
representations = None # Custom response representations
method_decorators = [] # Decorators applied to all methods
def __init__(self, api=None, *args, **kwargs):
"""
Initialize the resource.
Args:
api (Api, optional): Associated API instance
*args: Additional arguments
**kwargs: Additional keyword arguments
"""
def dispatch_request(self, *args, **kwargs):
"""
Dispatch the request to the appropriate HTTP method handler.
Args:
*args: URL route arguments
**kwargs: URL route keyword arguments
Returns:
Response: HTTP response
"""
def validate_payload(self, func):
"""
Validate request payload against expected model.
Args:
func (callable): Handler function to validate for
"""
# HTTP method handlers (implement as needed)
def get(self, *args, **kwargs):
"""Handle GET requests."""
def post(self, *args, **kwargs):
"""Handle POST requests."""
def put(self, *args, **kwargs):
"""Handle PUT requests."""
def patch(self, *args, **kwargs):
"""Handle PATCH requests."""
def delete(self, *args, **kwargs):
"""Handle DELETE requests."""
def head(self, *args, **kwargs):
"""Handle HEAD requests."""
def options(self, *args, **kwargs):
"""Handle OPTIONS requests."""Namespace Class
Groups related resources together with shared configuration, similar to Flask Blueprints but with additional API documentation features.
class Namespace:
def __init__(self, name, description=None, path=None, decorators=None,
validate=None, authorizations=None, ordered=False, **kwargs):
"""
Initialize the namespace.
Args:
name (str): Namespace name
description (str, optional): Namespace description
path (str, optional): URL path prefix
decorators (list, optional): Decorators to apply to all resources
validate (bool, optional): Enable request validation
authorizations (dict, optional): Authorization definitions
ordered (bool): Preserve field ordering in models
**kwargs: Additional namespace options
"""
def add_resource(self, resource, *urls, **kwargs):
"""
Add a resource to this namespace.
Args:
resource (Resource): Resource class to add
*urls (str): URL routes for the resource
**kwargs: Additional route arguments
"""
def route(self, *urls, **kwargs):
"""
Decorator to add a resource route to this namespace.
Args:
*urls (str): URL routes
**kwargs: Route arguments
Returns:
callable: Decorator function
"""
def model(self, name=None, model=None, **kwargs):
"""
Register a model in this namespace.
Args:
name (str, optional): Model name
model (dict or Model, optional): Model definition
**kwargs: Model fields
Returns:
Model: Registered model
"""
def clone(self, name, model, **kwargs):
"""
Clone an existing model in this namespace.
Args:
name (str): New model name
model (Model): Model to clone
**kwargs: Field modifications
Returns:
Model: Cloned model
"""
def inherit(self, name, *parents, **kwargs):
"""
Create an inherited model in this namespace.
Args:
name (str): New model name
*parents (Model): Parent models
**kwargs: Additional fields
Returns:
Model: Inherited model
"""
def expect(*inputs, validate=None):
"""
Namespace-specific expect decorator.
Args:
*inputs: Expected input models or parsers
validate (bool, optional): Enable validation
Returns:
callable: Decorator function
"""
def marshal_with(fields, **kwargs):
"""
Namespace-specific marshal_with decorator.
Args:
fields (dict or Model): Fields for marshalling
**kwargs: Marshal options
Returns:
callable: Decorator function
"""
def marshal_list_with(fields, **kwargs):
"""
Namespace-specific marshal_list_with decorator.
Args:
fields (dict or Model): Fields for marshalling
**kwargs: Marshal options
Returns:
callable: Decorator function
"""
def doc(self, shortcut=None, **kwargs):
"""
Namespace-specific documentation decorator.
Args:
shortcut (str, optional): Documentation shortcut
**kwargs: Documentation parameters
Returns:
callable: Decorator function
"""
def hide(self):
"""
Decorator to hide resources from documentation.
Returns:
callable: Decorator function
"""
def deprecated(self):
"""
Decorator to mark resources as deprecated.
Returns:
callable: Decorator function
"""
def header(self, name, description=None, **kwargs):
"""
Namespace-specific header documentation decorator.
Args:
name (str): Header name
description (str, optional): Header description
**kwargs: Additional header parameters
Returns:
callable: Decorator function
"""
def produces(self, mimetypes):
"""
Namespace-specific produces decorator.
Args:
mimetypes (list): Supported MIME types
Returns:
callable: Decorator function
"""
def response(self, code, description, model=None, **kwargs):
"""
Namespace-specific response documentation decorator.
Args:
code (int): HTTP status code
description (str): Response description
model (Model, optional): Response model
**kwargs: Additional response parameters
Returns:
callable: Decorator function
"""
def errorhandler(self, exception):
"""
Register a namespace-specific error handler.
Args:
exception (Exception): Exception class
Returns:
callable: Decorator function
"""
def param(self, name, description=None, **kwargs):
"""
Decorator for documenting URL parameters.
Args:
name (str): Parameter name
description (str, optional): Parameter description
**kwargs: Additional parameter options
Returns:
callable: Decorator function
"""
@property
def path(self):
"""
Get the namespace URL path.
Returns:
str: URL path prefix
"""
@property
def payload(self):
"""
Get the current request payload for this namespace.
Returns:
dict: Request payload data
"""Usage Examples
Basic API Setup
from flask import Flask
from flask_restplus import Api, Resource
app = Flask(__name__)
api = Api(
app,
version='1.0',
title='My API',
description='A simple demonstration API',
doc='/doc/'
)
@api.route('/hello')
class HelloWorld(Resource):
def get(self):
return {'message': 'Hello, World!'}
if __name__ == '__main__':
app.run(debug=True)Using Namespaces
from flask import Flask
from flask_restplus import Api, Resource, Namespace
app = Flask(__name__)
api = Api(app, doc='/doc/')
# Create namespaces
users_ns = api.namespace('users', description='User operations')
posts_ns = api.namespace('posts', description='Post operations')
@users_ns.route('/')
class UserList(Resource):
def get(self):
return [{'id': 1, 'name': 'John Doe'}]
@posts_ns.route('/')
class PostList(Resource):
def get(self):
return [{'id': 1, 'title': 'First Post', 'author_id': 1}]Advanced API Configuration
from flask import Flask
from flask_restplus import Api
app = Flask(__name__)
# Advanced API configuration
api = Api(
app,
version='2.0',
title='Advanced API',
description='An API with advanced configuration',
terms_url='http://example.com/terms',
license='MIT',
license_url='http://opensource.org/licenses/MIT',
contact='API Support',
contact_email='support@example.com',
doc='/documentation/',
validate=True, # Enable request validation
ordered=True, # Preserve field ordering
prefix='/api/v2' # URL prefix for all routes
)Install with Tessl CLI
npx tessl i tessl/pypi-flask-restplus