fixes tintoy#76

docs/conf.py

@@ -54,6 +54,16 @@
 # The master toctree document.
 master_doc = 'index'
 
+autodoc_default_options = {
+    'members': True,
+}
+autodoc_default_flags = [
+    'show-inheritance'
+]
+autodoc_typehints = "description"
+autoclass_content = 'both'
+
+
 # General information about the project.
 project = u'SeqLog'
 copyright = u"2016, Adam Friedman"

docs/index.rst

@@ -17,6 +17,7 @@ Contents:
 
    readme
    installation
+   migration
    usage
    usage-gunicorn
    Modules <api/modules>

docs/migration.rst

@@ -0,0 +1,22 @@
+===============================
+Migration guide from 0.4 to 0.5
+===============================
+
+First of all, the official way to configure Seq is via
+
+.. autofunction:: seqlog.configure_from_dict
+
+Alternatively you can call
+
+.. autofunction:: seqlog.configure_from_file
+
+
+.. warning:: DO NOT call :code:`logging.config.fromDict`
+
+Then, FeatureFlags were completely obliterated and moved to SeqLogHandler's constructor.
+
+Then, the SeqLogHandler accepts way more arguments that you can define in this dict:
+
+.. autoclass:: seqlog.structured_logging.SeqLogHandler
+    :members:
+

docs/usage.rst

@@ -58,6 +58,8 @@ First, create your configuration file (e.g. ``/foo/bar/my_config.yml``):
 
     # Configure logging from scratch.
     disable_existing_loggers: True
+    override_root_logger: True
+    use_structured_logger: True
 
     # Configure the root logger to use Seq
     root:
@@ -98,7 +100,7 @@ First, create your configuration file (e.g. ``/foo/bar/my_config.yml``):
       seq:
         style: '{'
 
-Then, call ``seqlog.configure_from_file()``:
+Then, call :func:`seqlog.configure_from_file`:
 
 .. code-block:: python
 
@@ -115,11 +117,9 @@ Then, call ``seqlog.configure_from_file()``:
 Configuring logging from a dictionary
 -------------------------------------
 
-.. deprecated:: 0.5.0
-    Use logging.config.dictConfig() directly
-
 Seqlog can also use a dictionary to describe the desired logging configuration.
 This dictionary has the schema specified in Python's `logging.config <https://docs.python.org/3/library/logging.config.html#logging-config-dictschema>`_ module.
+With some extra options described in :func:`seqlog.configure_from_dict`.
 
 .. code-block:: python
 
@@ -137,29 +137,6 @@ This dictionary has the schema specified in Python's `logging.config <https://do
     another_logger = logging.getLogger('another_logger')
     another_logger.info('This is another logger.')
 
-Note that you can pass flags that were previously given to :func:`seqlog.configure_from_dict` directly in the dictionary, eg.
-
-.. autofunction:: seqlog.configure_from_dict
-
-.. code-block:: python
-
-    a['handlers']['console'] = {
-        'class': 'seqlog.structured_logging.ConsoleStructuredLogHandler',
-        'formatter': 'standard'
-        'override_root_logger': True
-        'use_structured_logging': True,
-        'use_clef': True        
-    }
-    logging.config.dictConfig(a)
-
-Basically all of the arguments in
-
-.. autoclass:: seqlog.structured_logging.BaseStructuredLogHandler
-
-can be put there.
-
-Note that only first arguments that were previously passed globally will be set. Argument configured once in one logger
-won't pass to another.
 
 Batching and auto-flush
 -----------------------

seqlog/__init__.py

@@ -7,7 +7,6 @@
 
 import yaml
 
-from seqlog.feature_flags import FeatureFlag, configure_feature
 from seqlog.structured_logging import StructuredLogger, StructuredRootLogger, _override_root_logger
 from seqlog.structured_logging import SeqLogHandler, ConsoleStructuredLogHandler
 from seqlog.structured_logging import get_global_log_properties as _get_global_log_properties
@@ -23,32 +22,34 @@
 
 def configure_from_file(file_name):
     """
-    Configure Seq logging using YAML-format configuration file.
+    Configure Seq logging using YAML-format configuration file. Essentially loads the YAML, and invokes
+    :func:`configure_from_dict`.
 
     Uses `logging.config.dictConfig()`.
     """
 
     with open(file_name) as config_file:
         config = yaml.load(config_file, Loader=yaml.SafeLoader)
 
-    logging.config.dictConfig(config)
+    configure_from_dict(config)
 
 
 def configure_from_dict(config):
     """
-    Configure Seq logging using a dictionary.
-
-    Uses `logging.config.dictConfig()`.
+    Configure Seq logging using a dictionary. Use it instead of logging.config.dictConfig().
 
-    .. deprecated: 0.5.0
-        Use logging.config.dictConfig() directly.
+    Extra parameters you can specify (as dictionary keys).
 
-    Note that if you provide None to any of the default arguments, it just won't get changed (ie. it will stay the same).
+    * `use_structured_logger` - this will configure Python logging environment to use a StructuredLogger, ie. one that
+       understands keyword arguments
+    * `override_root_logger` - overrides root logger with a StructuredLogger
 
-    :param config: A dict containing the configuration.
-    :type config: dict
+    The rest will be passed onto logging.config.dictConfig()
     """
-    warnings.warn('This is deprecated, use logging.config.dictConfig() directly', DeprecationWarning)
+    if config.pop('use_structured_logger', False):
+        logging.setLoggerClass(StructuredLogger)
+    if config.pop('override_root_logger', False):
+        _override_root_logger()
     logging.config.dictConfig(config)
 
 
@@ -86,19 +87,15 @@ def log_to_seq(server_url, api_key=None, level=logging.WARNING,
     :return: The `SeqLogHandler` that sends events to Seq. Can be used to forcibly flush records to Seq.
     :rtype: SeqLogHandler
     """
-
-    configure_feature(FeatureFlag.EXTRA_PROPERTIES, support_extra_properties)
-    configure_feature(FeatureFlag.STACK_INFO, support_stack_info)
-    configure_feature(FeatureFlag.IGNORE_SEQ_SUBMISSION_ERRORS, ignore_seq_submission_errors)
-    configure_feature(FeatureFlag.USE_CLEF, use_clef)
-
     logging.setLoggerClass(StructuredLogger)
 
     if override_root_logger:
         _override_root_logger()
 
     log_handlers = [
-        SeqLogHandler(server_url, api_key, batch_size, auto_flush_timeout, json_encoder_class)
+        SeqLogHandler(server_url, api_key, batch_size, auto_flush_timeout, json_encoder_class,
+                      support_extra_properties=support_extra_properties, support_stack_info=support_stack_info,
+                      use_clef=use_clef, ignore_seq_submission_errors=ignore_seq_submission_errors)
     ]
 
     if additional_handlers: