Welcome to apy’s documentation!¶

Customizing the path matching Requirements¶

Customizing the action method name of the controller class¶

Adding HTTP Method Requirements¶

In addition to the URL, you can also match on the method of the incoming request (i.e. GET, HEAD, POST, PUT, DELETE). Suppose you have a contact form with two controllers - one for displaying the form info (on a GET request) and one for processing the form when it’s submitted (on a POST request). This can be accomplished with the following route configuration:

Despite the fact that these two routes have identical paths (/contact), the first route will match only GET requests and the second route will match only POST requests. This means that you can display the form info and submit the form via the same URL, while using distinct controllers for the two actions.

methods: [GET]

methods: [GET, POST]

methods:
  - GET
  - DELETE

methods:
  - OPTIONS

Adding Protocol Requirements to use HTTPS or HTTP¶

Sometimes, you want to secure some routes and be sure that they are only accessed via the HTTPS protocol.

This can be accomplished with the following route configuration:

routes:
    contact:
        path:       /contact
        controller: myapplication.main.ContactController
        protocols:  [https]

protocols: [http]

protocols: [http, https]

protocols:
  - https
  - http

protocols:
  - https

Adding Host Requirements¶

What is a Service Container¶

A Service Container (or dependency injection container) is simply a python object that manages the instantiation of services (objects). For example, suppose you have a simple python class that delivers email messages. Without a service container, you must manually create the object whenever you need it:

from myapplication.mailer import Mailer

mailer = Mailer('sendmail')
mailer.send('felix@example.com', ...)

This is easy enough. The imaginary Mailer class allows you to configure the method used to deliver the email messages (e.g. sendmail, smtp, etc).

But what if you wanted to use the mailer service somewhere else? You certainly don’t want to repeat the mailer configuration every time you need to use the Mailer object. What if you needed to change the transport from sendmail to smtp everywhere in the application? You’d need to hunt down every place you create a Mailer service and change it.

The Services container allows you to standardize and centralize the way objects are constructed in your application.

Creating/Configuring Services in the Container¶

A better answer is to let the service container create the Mailer object for you. In order for this to work, you must teach the container how to create the Mailer service. This is done via configuration, which would be specified in YAML:

# config/settings_prod.yml
...
services:
    my_mailer:
        class:        myapplication.mailer.Mailer
        arguments:    [sendmail]
...

An instance of the myapplication.mailer.Mailer object is now available via the service container. The services container is available in any traditional apy controller where you can access the services of the container via the self._services.get(name) method:

1
2
3
4
5
6
7
8
9

# myapplication/hello.py
from apy.handler import Controller
...
class HelloController(Controller):
    def action(self):
        ...
        mailer = self._services.get('my_mailer')
        mailer.send('felix@example.com', ...)
        ...

When you ask for the my_mailer service from the container, the container constructs the object and returns it. This is another major advantage of using the service container. Namely, a service is never constructed until it’s needed. If you define a service and never use it on a request, the service is never created. This saves memory and increases the speed of your application. This also means that there’s very little or no performance hit for defining lots of services. Services that are never used are never constructed.

As an added bonus, the Mailer service is only created once and the same instance is returned each time you ask for the service. This is almost always the behavior you’ll need (it’s more flexible and powerful).

You can pass the arguments as list or dict.

You can call functions after object instantiation with:

...
services:
    my_mailer:
        class:        myapplication.mailer.Mailer
        arguments:    [sendmail]
        calls:
            - [ set_name, 'Felix Carmona']
            - [ inject_something,  [1, 2, 3]]
            - [ inject_something,  [2, 3]]
            - [ set_location,  {'city': 'Barcelona', 'country': 'Spain'}]
...

The available methods for the service container (available in the controller as self._services):

• set(key, value): Sets a service object by name.
• get(key): Returns a service object by name.
• has(key): Returns True if the service definition exists or if the service object is instantiated, False otherwise.
• remove(key): Removes a service object and service definition by name.
• add(parameters): Adds a dict of services objects.
• keys(): Returns the services keys.

Using the Parameters to build Services¶

The creation of new services (objects) via the container is pretty straightforward. Parameters make defining services more organized and flexible:

parameters:
    my_mailer_class:      myapplication.mailer.Mailer
    my_mailer_transport:  sendmail

services:
    my_mailer:
        class:        "{{ my_mailer_class }}"
        arguments:    ["{{ my_mailer_transport }}"]

The end result is exactly the same as before - the difference is only in how you defined the service. By surrounding the my_mailer.class and my_mailer.transport strings in double bracket keys ({{ }}) signs, the container knows to look for parameters with those names. Parameters can deep reference other parameters that references other parameters, and will be resolved anyway.

The purpose of parameters is to feed information into services. Of course there was nothing wrong with defining the service without using any parameters. Parameters, however, have several advantages:

• separation and organization of all service “options” under a single parameters key
• parameter values can be used in multiple service definitions

The choice of using or not using parameters is up to you.

Importing Configuration with imports¶

The service container is built using this single configuration resource (config/settings_*.yml by default). All other service configuration must be imported from inside this file (writing they in this file, or including them via the imports directive). This gives you absolute flexibility over the services in your application.

So far, you’ve placed your my_mailer service container definition directly in the application configuration file (e.g. config/settings_prod.yml ).

First, move the my_mailer service container definition into a new yaml file.

# config/services.yml
parameters:
    my_mailer_class:      myapplication.mailer.Mailer
    my_mailer_transport:  sendmail

services:
    my_mailer:
        class:        "{{my_mailer._lass}}"
        arguments:    ["{{my_mailer_transport}}"]

The definition itself hasn’t changed, only its location. Of course the service container doesn’t know about the new resource file. Fortunately, you can easily import the resource file using the imports key in the application configuration.

# config/settings_prod.yml
imports:
    - services.yml
...

The imports directive allows your application to include service container configuration resources from any other location. The resource location, for files, is the relative (from config path) or absolute path to the resource file.

Referencing (Injecting) Services¶

You can of course also reference services

Start the string with @ to reference a service in YAML.

parameters:
    my_mailer:
        class:      myapplication.mailer.Mailer
        transport:  sendmail

services:
    my_mailer:
        class: "{{ my_mailer.class }}"
        arguments:
            - "{{ my_mailer.transport }}"
    my_mailer_manager:
        class: myapplication.mailer.MailerManager
        arguments:
            - "@my_mailer"

the my_mailer service will be injected in the my_mailer_manager