vinegar.cli.server

Vinegar server daemon.

If executed as a Python script, this module starts a Vinegar server, looking for a configuration file in /etc/vinegar/vinegar-server.yaml.

The path to the configuration file can be overridden through the --config-file command line argument.

Instead of executing this module as a script, it can be imported and its run_server function can be used to start the server. In this case, the configuration is expected to be passed to run_server in the form of a dictionary.

The configuration file uses the YAML syntax and has the following keys (all of them are optional):

data_sources:

List of data sources. Each item in the list must be a dictionary. This dictionary must have a key name that specifies the type of the data source. Please refer to the documentation of vinegar.data_source.get_data_source to learn more about how the name is resolved. All other keys are used for the configuration dictionary that is passed to the data source. It is perfectly legal to use multiple data sources with the same name, but having a different configuration. Please refer to the documentation of the data sources to learn more about the configuration options for each data sources. The resulting list of data sources is passed to get_composite_datasource in order to create a single data source that combines them all. The behavior of the compositve data source is also controlled by the data_sources_merge_lists option.

data_sources_merge_lists:

Flag controlling the behavior of the composite data source that is created for the list of data_sources. The composite data source merges the data returned by each data source with the data from the previous data sources. This happens by merging mappings, preserving keys that are present in the previous data, but not in the data from the next data source. This process also applies to nested mappings. If data_sources_merge_lists is set to True, sequences are also merged, meaning that elements that are not present in the list in the previous data are added to the list. If False (the default), sequences replace each other, removing all elements that were only present in the previous data.

data_sources_merge_sets:

Flag controlling the behavior of the composite data source that is created for the list of data_sources. The composite data source merges the data returned by each data source with the data from the previous data sources. This happens by merging mappings, preserving keys that are present in the previous data, but not in the data from the next data source. This process also applies to nested mappings. If data_sources_merge_sets is set to True (the default), sets are also merged, meaning that the resulting set is the union of the set in the previous data and the set returned by the data source. If False, sets replace each other, removing all elements that were only present in the previous data.

http:

Dictionary of configuration options for the HTTP server. The options are passed on to vinegar.server.http.create_http_server. The only exception is the request_handlers option. That option expects a list, where each item is a dictionary. This dictionary must have a key name that specifies the type of the request handler. Please refer to the documentation of vinegar.request_handler.get_http_request_handler to learn more about how the name is resolved. All other keys are used for the configuration dictionary that is passed to the request handler. It is perfectly legal to use multiple request handlers with the same name, but having a different configuration. Please refer to the documentation of the request handlers to learn more about the configuration options for each request handler.

logging_config_file:

Path to a logging configuration file. This file must be in the format expected by logging.config.fileConfig. This configuration option cannot be used together with the logging_level option.

logging_level:

Logging level to be used. Can be one of CRITICAL, ERROR, WARN, INFO (the default), or DEBUG. This configuration option cannot be used together with the logging_config_file option.

tftp:

Dictionary of configuration options for the TFTP server. The options are passed on to vinegar.server.tftp.create_tftp_server. The only exception is the request_handlers option. That option expects a list, where each item is a dictionary. This dictionary must have a key name that specifies the type of the request handler. Please refer to the documentation of vinegar.request_handler.get_tftp_request_handler to learn more about how the name is resolved. All other keys are used for the configuration dictionary that is passed to the request handler. It is perfectly legal to use multiple request handlers with the same name, but having a different configuration. Please refer to the documentation of the request handlers to learn more about the configuration options for each request handler.

vinegar.cli.server.main()

Run Vinegar server.

This function parses the command-line arguments, calls reader_server_config, and subsequently calls run_server.

vinegar.cli.server.read_server_config(config_file: str | None = None) → Mapping[str, Any]

Read the server configuration.

If the configurtion file cannot be read (because it does not exist, permissions are insufficient, or it is not a valid YAML file), an exception is raised.

The returned object can then be passed to run_server.

Parameters:

config_file – path to the configuration file. If None a platform specifc default value is used.

Returns:

configuration read from the file.

vinegar.cli.server.run_server(config: Mapping[str, Any]) → None

Run the Vinegar server.

This function only returns when it is interrupted from the keyboard or when the process receives a SIGTERM.

This function raises an exception if the configuration object is invalid or if the server cannot be started.

Parameters:

config – configuration object used by the server. Please refer to the module documentation for a description of the structure of the configuration object.