Often times you'll find yourself needing something particular to an interface (say a header, a session, or content_type) but don't want to tie your function

to a single interface. To support this: hug introduces the concept of `directives`. In hug directives are simply arguments that have been registered to automatically provide a parameter value based on knowledge known to the interface.

For example - this is the built in session directive:

Then when using this directive in your code, you can either specify the directive via type annotation:

Or, prefixing the argument with `hug_`:

- hug.directives.Timer (hug_timer=precision): Stores the time the interface was initially called, returns how much time has passed since the function was called if casted as a float. Automatically converts to a the time taken when returned as part of a JSON structure. The default value is used to specify the float precision desired when keeping track of the time passed

- hug.directives.module (hug_module): Passes along the module that contains the API associated with this endpoint

- hug.directives.api (hug_api): Passes along the hug API singleton associated with this endpoint

- hug.directives.api_version (hug_api_version): Passes along the version of the API being called

- hug.directives.documentation (hug_documentation): Generates and passes along the entire set of documentation for the API the endpoint is contained within

- hug.directives.session (hug_session=context_name): Passes along the session associated with the current request. The default value is used to provide a different key where the value is stored on the request.context object.

- hug.directives.user (hug_user): Passes along the user object associated with the request

- hug.directives.CurrentAPI (hug_current_api): Passes along a smart version aware API caller, to enable calling other functions within your API with reissurence the correct function is being called for the version of the API being requested

hug provides the `@hug.directive()` to enable creation of new directives. It takes one argument: apply_globally which defaults to False.

If you set this parameter to True the hug directive will be automatically made available as a magic `hug_` argument on all endpoints outside of just your defined API. This is not a concern if your applying directives via type annotation.

The most basic directive will simply take an optional default value, and **kwargs:

It's important to always accept **kwargs for directive functions as each interface get's to decide it's own set of

key word arguments to send to the directive, which can then be used to pull-in information for the directive.

Independ of what interface a directive is being ran through, the following key word arguments will be passed to it:

- `interface` - the interface that the directive is being ran through. Useful for conditionally injecting different data via the decorator depending on the interface it is being called through, as demonstrated at the bottom of this section

- `api` - the API singleton associated with this endpoint

Directives are passed the following additional keyword parameters when they are being ran through an HTTP interface:

- `response`: The HTTP response object that will be returned for this request

- `request`: The HTTP request object that caused this interface to be called

- `api_version`: The version of the endpoint being hit

Directives get one additional argument when they are being ran through a command line interface:

- `argparse`: The argparse instance created to parse command line arguments

Every endpoint that is exposed via an external facing interface will need to output the data returned in a standard format that users of the interface will be able to understand.

The default output format for all hug APIs is JSON unless you explicitly specify a different default output_format:

Or to specify an output_format for a specific endpoint, simply specify the output format within it's router:

Remember that you can also always use route chaining to specify an output format for a group of endpoints within an API:

Finally, it's perfectly valid for an output format to in essence be a collection of other output format's that get conditionally used. For example using the built in suffix output format:

In this case if the endpoint is accesed via my_endpoint.js the output type will be JSON, however if it's accesed via .html the output type will be HTML.

Built in hug output formats

hug provides a large catolog of built in output formats that can be used to build useful APIs right away:

- `hug.output_format.json`: The default hug output formatter for all endpoints, outputs in Javascript Serialized Object Notation (JSON)

- `hug.output_format.text`: Outputs in a plain text format

- `hug.output_format.html`: Outputs Hyper Text Markup Language (HTML)

- `hug.output_format.json_camelcase`: Outputs in the JSON format but first converts all keys to camelCase to better conform to Javascript coding standards.

- `hug.output_format.pretty_json`: Outputs in the JSON format, with extra white-space to improve human readability

- `hug.output_format.image(format)`: Outputs an image (of the specified format)

Automatically works on returned file names, streams, or objects that produce an image on read, save, or render

- `hug.output_format.video(video_type, video_mime, doc)`: Streams a video back to the user in the specified format

Automatically works on returned file names, streams, or objects that produce a video on read, save, or render

- `hug.output_format.file`: Will dynamically determine and stream a file based on its content. Automatically works on returned file names and streams

- `hug.output_format.on_content_type(handlers={content_type: output_format}, default=None)`: Dynamically changes the output format based on the request content type

- `hug.output_format.suffix(handlers={suffix: output_format}, default=None)`: Dynamically changes the output format based on a suffix at the end of the requested path

- `hug.output_format.prefix(handlers={suffix: output_format}, defualt=None)`: Dynamically changes the output format based on a prefix at the begining of the requested path

A common pattern is to only apply the output format validation errors aren't passed in since it's hard to deal with this for several formats (such as images) and it may make more sense to simply return the error as JSON. hug makes this pattern simple as well with the `hug.output_format.on_valid` decorator:

current = "2.0.1"