simpl server

[stavxyz]

This change installs a simpl command into your environment during package installation using the console_scripts entry point. The first available subcommand is server. You can now use simpl server to quickly run your app.

The interface is similar to that of bottle's "command line interface".

The simpl/server boilerplate and interface can be used a few different ways:

1. Point simpl server to your routes

Example:

# test_app.py

import bottle

@bottle.get('/')
def hello():
    return 'Hello World!'

Run the command

simpl server -a test_app -p 8888
Bottle v0.12.8 server starting up (using XTornadoServer())...
Listening on http://127.0.0.1:8888/
Hit Ctrl-C to quit.

test it...

you@localhost $ http get localhost:8888
HTTP/1.1 200 OK
Content-Length: 12
Content-Type: text/html; charset=UTF-8
Server: TornadoServer/4.2

Hello World!

Of course, this might not be how you choose to continue as your app matures

2. Attach simpl's server subcommand to your parser

Admittedly, this technique is a little strange, and the code must be in the exact order as written below. But it works.

import argparse

from simpl import server


parser = argparse.ArgumentParser()
server_parser = server.attach_parser(parser.add_subparsers())
server_parser.set_defaults(func=server.run)
args = awesome_parser.parse_args()

conf = config.init(options=server.OPTIONS)
conf.parse()
args._func(conf)

3. Just use the server.OPTIONS, and run bottle however you want.

import bottle
from simpl import server

conf = server.CONFIG
conf.parse()

b = bottle.Bottle()
# add middleware, routes to Bottle instance
conf['app'] = b
server.run(conf)

---

--help

you@localhost$ simpl server --help
usage: simpl server [-h] [--ini PATH] [--app APP] [--host HOST] [--port PORT]
                    [--server SERVER] [--debug-server] [--quiet-server]
                    [--no-reloader] [--interval INTERVAL]
                    [--adapter-options [ADAPTER_OPTIONS [ADAPTER_OPTIONS ...]]]

optional arguments:
  -h, --help            show this help message and exit

initialization (metaconfig) arguments:
  evaluated first and can be used to source an entire config

  --ini PATH            Source some or all of the options from this ini file.

Server Options:
  --app APP, -a APP     WSGI application to load by name.
                        Ex: package.module gets the module
                            package.module:name gets the variable 'name'
                            package.module.func() calls func() and gets the result
  --host HOST           Server address to bind to. (default: 127.0.0.1)
  --port PORT, -p PORT  Server port to bind to. (default: 8080)
  --server SERVER, -s SERVER
                        Server adapter to use. To see more, run:
                        `python -c "import bottle;print(bottle.server_names.keys())"`
                         (default: xtornado)
  --debug-server        Run bottle server with debug=True which is useful
                        for development or troubleshooting. Warning: This
                        may expose raw tracebacks and unmodified error
                        messages in responses! Note: this is not an option
                        to configure DEBUG level logging. (default: False)
  --quiet-server        Suppress bottle's output to stdout and stderr,
                        e.g. "Bottle v0.12.8 server starting up..." and
                        others. (default: False)
  --no-reloader         Disable bottle auto-reloading server, which
                        automatically restarts the server when file
                        changes are detected. Note: some server adapters,
                        such as eventlet, do not support auto-reloading. (default: False)
  --interval INTERVAL, -i INTERVAL
                        Auto-reloader interval in seconds (default: 1)
  --adapter-options [ADAPTER_OPTIONS [ADAPTER_OPTIONS ...]], -o [ADAPTER_OPTIONS [ADAPTER_OPTIONS ...]]
                        Key-value pairs separated by '=' to be passed to
                        the underlying server adapter, e.g. XEventletServer,
                        and are mapped to the adapter's self.options
                        instance attribute. Example usage:
                          simpl server -s xeventlet -o keyfile=~/mykey ciphers=GOST94

[ryandub]

+1 from me!

[ziadsawalha]

Nice! A couple of notes:

• could you add docs to the README?
• Is it possible call it from a project's entry point instead of using the simpl commandline and entry point? I.e. right now you show how to use the simpl command-line separately and pass it any entry point (could be anything, not even in the project that is using simpl). But for many of our projects we use simpl.config and have many options that we control from inside the project (like customizing the program name) and we have project-specific entry points. For those projects, we might want to append a set of server options and then expose the start command from the project itself. For example:

"""Project Awesome."""

from simpl import config
from simpl import log
from simpl import server

SIMPL_OPTIONS = log.OPTIONS + server.OPTIONS
OPTIONS = MY_OPTIONS + SIMPL_OPTIONS

if __name__ == "__main__":
    conf = config.init(options=OPTIONS)
    log.configure(conf)
    conf.parse()
    if conf.command == "server":
        server.run(name="awesome", conf)
    else:
        do_something_else()

So the command would be similar to what you have in the PR description, but would be the project entry point, no simpl's:

$ awesome server --help
usage: awesome server [-h] [--ini PATH] [--app APP] [--host HOST] [--port PORT]
                    [--server SERVER] [--debug-server] [--quiet-server]
                    [--no-reloader] [--interval INTERVAL]
                    [--adapter-options [ADAPTER_OPTIONS [ADAPTER_OPTIONS ...]]]

optional arguments:
  -h, --help            show this help message and exit

initialization (metaconfig) arguments:
  evaluated first and can be used to source an entire config

  --ini PATH            Source some or all of the options from this ini file.

Server Options:
  --app APP, -a APP     WSGI application to load by name.
                        Ex: package.module gets the module
                            package.module:name gets the variable 'name'
                            package.module.func() calls func() and gets the result
  --host HOST           Server address to bind to. (default: 127.0.0.1)
  --port PORT, -p PORT  Server port to bind to. (default: 8080)
  --server SERVER, -s SERVER
                        Server adapter to use. To see more, run:
                        `python -c "import bottle;print(bottle.server_names.keys())"`
                         (default: xtornado)
  --debug-server        Run bottle server with debug=True which is useful
                        for development or troubleshooting. Warning: This
                        may expose raw tracebacks and unmodified error
                        messages in responses! Note: this is not an option
                        to configure DEBUG level logging. (default: False)
  --quiet-server        Suppress bottle's output to stdout and stderr,
                        e.g. "Bottle v0.12.8 server starting up..." and
                        others. (default: False)
  --no-reloader         Disable bottle auto-reloading server, which
                        automatically restarts the server when file
                        changes are detected. Note: some server adapters,
                        such as eventlet, do not support auto-reloading. (default: False)
  --interval INTERVAL, -i INTERVAL
                        Auto-reloader interval in seconds (default: 1)
  --adapter-options [ADAPTER_OPTIONS [ADAPTER_OPTIONS ...]], -o [ADAPTER_OPTIONS [ADAPTER_OPTIONS ...]]
                        Key-value pairs separated by '=' to be passed to
                        the underlying server adapter, e.g. XEventletServer,
                        and are mapped to the adapter's self.options
                        instance attribute. Example usage:
                          simpl server -s xeventlet -o keyfile=~/mykey ciphers=GOST94

If that is possible, could you show an example of you recommend it be done? If not, can we explore making that possible?

[stavxyz]

@ziadsawalha Thanks for the comments.

Thinking/coding out loud...

"""Project Awesome."""

from simpl import config
from simpl import log
from simpl import server
from simpl.utils import cli as cli_utils

SIMPL_OPTIONS = log.OPTIONS + server.OPTIONS
OPTIONS = MY_OPTIONS + SIMPL_OPTIONS

# Where MY_OPTIONS have some server options
# with group='Server Options'

# Also, project awesome defines the `awesome`
# console_scripts entry_point which points to
# this file's main()

def main():

    awesome_parser = cli_utils.HelpfulParser(prog='awesome')
    server_parser = server.attach_parser(awesome_parser.add_subparsers())
    server_parser.set_defaults(_func=server.run)
    args = awesome_parser.parse_args()

    conf = config.init(options=OPTIONS)
    conf.parse()
    args._func(conf)


if __name__ == "__main__":

    main()

Maybe we could improve on this?

[ziadsawalha]

Where MY_OPTIONS have some server options with group='Server Options

Is that needed if we provide server.OPTIONS in simpl? See SIMPL_OPTIONS = log.OPTIONS + server.OPTIONS

[stavxyz]

@ziadsawalha it's not needed, but it would allow your app's options to be grouped with the server options provided by simpl in the help/usage output.

[ziadsawalha]

I noticed that you changed this from --debug\-d to --debug-server. Why not just have it enabled when --debug\-d is supplied? I'm not sure I see the need/benefit for --debug\-d and --debug-server being separate.

--debug\-d already generates gobs of data (as might be expected from a debug mode), so having it output traces in bottle also seems acceptable. Note: for the record, --verbose is how to log heavily but not dump gobs of data out.

I do recognize the challenge of addressing the duplicate --debug\-d option in server.OPTIONS and log.OPTIONS if we did that. IMO, we should try to solve that and keep only one -d flag.

[stavxyz]

@ziadsawalha I am not sure how to handle the conflicting options. I believe --debug and --debug-server should mean different things, so I am not sure about merging them. And if I did merge them, where would the option live? In server.py or log.py ? What would the description be? Or in a common options module?

I think --debug-server WRT the bottle server should (read: will eventually) mean that the traceback will be returned in the json payload if FormatExceptionMiddleware catches it. See #83

[ziadsawalha]

To resolve the conflict, --debug\-d could move into config.py and become a built-in option in config.py. If putting simpl in debug mode starts to mean more than just logging, then it would no longer be appropriate for that option to be in log.py.

I believe --debug and --debug-server should mean different things

So would we have --debug-db, --debug-config, etc... for each module?

[ziadsawalha]

Thanks for documenting "Attach simpl's server subcommand to your parser". Could you add that markdown to the code in the PR as well? Either in the server module docstrings or a readme? It should end up being the canonical "how to use this" text.

[ziadsawalha]

I struggled with this in https://github.com/checkmate/simpl/blob/master/tests/test_server.py#L109. I think this might not get correctly reflected in in test coverage.