Command Line Interface¶
Nameko ships with a command line interface to make hosting and interacting with services as easy as possible.
Running a Service¶
$ nameko run <module>[:<ServiceClass>]
Discover and run a service class. This will start the service in the foreground and run it until the process terminates.
It is possible to override the default settings using a --config
switch
$ nameko run --config ./foobar.yaml <module>[:<ServiceClass>]
and providing a simple YAML configuration file:
# foobar.yaml
AMQP_URI: 'pyamqp://guest:guest@localhost'
WEB_SERVER_ADDRESS: '0.0.0.0:8000'
rpc_exchange: 'nameko-rpc'
max_workers: 10
parent_calls_tracked: 10
LOGGING:
version: 1
handlers:
console:
class: logging.StreamHandler
root:
level: DEBUG
handlers: [console]
The LOGGING
entry is passed to logging.config.dictConfig()
and should conform to the schema for that call.
Config values can be read via the built-in Config dependency provider.
Environment variable substitution¶
YAML configuration files have support for environment variables.
You can use bash style syntax: ${ENV_VAR}
.
Optionally you can provide default values ${ENV_VAR:default_value}
.
Default values can contains environment variables recursively ${ENV_VAR:default_${OTHER_ENV_VAR:value}}
(note: this feature requires regex package).
# foobar.yaml
AMQP_URI: pyamqp://${RABBITMQ_USER:guest}:${RABBITMQ_PASSWORD:password}@${RABBITMQ_HOST:localhost}
To run your service and set environment variables for it to use:
$ RABBITMQ_USER=user RABBITMQ_PASSWORD=password RABBITMQ_HOST=host nameko run --config ./foobar.yaml <module>[:<ServiceClass>]
If you need to quote the values in your YAML file, the explicit !env_var
resolver is required:
# foobar.yaml
AMQP_URI: !env_var "pyamqp://${RABBITMQ_USER:guest}:${RABBITMQ_PASSWORD:password}@${RABBITMQ_HOST:localhost}"
If you need to use values as raw strings in your YAML file without them getting converted to native python,
the explicit !raw_env_var
resolver is required:
# foobar.yaml
ENV_THAT_IS_NEEDED_RAW: !raw_env_var "${ENV_THAT_IS_NEEDED_RAW:1234.5660}"
This will turn into the string value 1234.5660
, instead of a float number.
You can provide many levels of default values
# foobar.yaml
AMQP_URI: ${AMQP_URI:pyamqp://${RABBITMQ_USER:guest}:${RABBITMQ_PASSWORD:password}@${RABBITMQ_HOST:localhost}}
this config accepts AMQP_URI as an environment variable, if provided RABBITMQ_* nested variables will not be used.
The environment variable value is interpreted as YAML, so it is possible to use rich types:
# foobar.yaml
...
THINGS: ${A_LIST_OF_THINGS}
$ A_LIST_OF_THINGS=[A,B,C] nameko run --config ./foobar.yaml <module>[:<ServiceClass>]
the parser for environment variables will pair all brackets.
# foobar.yaml
LANDING_URL_TEMPLATE: ${LANDING_URL_TEMPLATE:https://example.com/{path}}
so the default value for this config will be https://example.com/{path}
Interacting with running services¶
$ nameko shell
Launch an interactive python shell for working with remote nameko services. This is a regular interactive interpreter, with a special module n
added
to the built-in namespace, providing the ability to make RPC calls and dispatch events.
Making an RPC call to “target_service”:
$ nameko shell
>>> n.rpc.target_service.target_method(...)
# RPC response
Dispatching an event as “source_service”:
$ nameko shell
>>> n.dispatch_event("source_service", "event_type", "event_payload")