Use an interface so we don't have to replace the milc.cli object

ci_tests

@@ -10,12 +10,10 @@ from pathlib import Path
 from shutil import rmtree
 from subprocess import CalledProcessError, DEVNULL, run
 
-from milc import set_metadata
-
-set_metadata(name='ci_tests', author='MILC', version='1.3.0')
-
 from milc import cli
 
+cli.milc_options(name='ci_tests', author='MILC', version='1.8.0')
+
 
 @cli.entrypoint('Run CI Tests...')
 def main(cli):

custom_logger

@@ -5,13 +5,13 @@ PYTHON_ARGCOMPLETE_OK
 """
 import logging
 
-from milc import set_metadata
+from milc import cli
 
 # Setup external logger
 logging.basicConfig(level=logging.DEBUG)
 logger = logging.getLogger('custom_logger')
 
-set_metadata(logger=logging.getLogger('custom_logger'))
+cli.milc_options(logger=logging.getLogger('custom_logger'))
 
 # Import milc
 from milc import cli

docs/logging.md

@@ -39,3 +39,31 @@ Users have several CLI arguments they can pass to control the output of logs. Th
     * Enable or disable ANSI color
 * `--unicode` and `--no-unicode`
     * Enable or disable unicode icons
+
+# Custom Loggers
+
+You may want to bypass MILC's logging and use your own logger instead. To do this use `cli.milc_options(logger=<MyLogger>)`. This should be done before you call `cli()` or do anything else.
+
+Example:
+
+```python
+import logging
+
+from milc import cli
+
+
+@cli.entrypoint('Hello, World!')
+def hello(cli):
+    cli.log.info('Hello, World!')
+
+if __name__ == '__main__':
+    my_logger = logging.getLogger('my-program')
+    # Configure my_logger the way you want/need here
+
+    cli.milc_options(logger=my_logger)
+    cli()
+
+```
+
+!!! warning
+    You should only call `cli.milc_options()` one time during your program's execution.

docs/metadata.md

@@ -1,13 +1,13 @@
 # MILC Metadata
 
-In order to initialize some things, such as the configuration file location and the version number reported by `--version`, MILC needs to know some basic information before you import `cli`. If you need to set the program's name, author name, and/or version number do it like this:
+In order to initialize some things, such as the configuration file location and the version number reported by `--version`, MILC needs to know some basic information before the entrypoint is called. You can use `cli.milc_options()` to set this information.
 
-```python
-from milc import set_metadata
-
-set_metadata(name='Florzelbop', version='1.0.0', author='Jane Doe')
+Example:
 
+```python
 from milc import cli
+
+cli.milc_options(name='Florzelbop', version='1.0.0', author='Jane Doe')
 ```
 
 You should only do this once, and you should do it as early in your program's execution as possible.
@@ -28,3 +28,7 @@ set_metadata(logger=custom_logger)
 
 from milc import cli
 ```
+
+## Deprecated: set_metadata()
+
+Earlier versions of MILC used `milc.set_metadata` instead. This is still supported but will throw a Deprecation warning.

docs/subcommand_config.md

@@ -8,6 +8,9 @@ Configuration for MILC applications is a key/value system. Each key consists of
 
 `import milc.subcommand.config`
 
+!!! warn
+    This must be imported after `cli.milc_options()` is used.
+
 Read on to see how users can utilize this subcommand.
 
 ## Simple Example

example

@@ -5,11 +5,11 @@ PYTHON_ARGCOMPLETE_OK
 """
 import os
 
-from milc import set_metadata
+from milc import cli
 
-set_metadata(name='example', author='Milc Milcenson', version='1.8.0')
+cli.milc_options(name='example', author='Milc Milcenson', version='1.8.0')
 
-from milc import cli
+# This needs to be imported after we use cli.milc_options()
 import milc.subcommand.config  # noqa
 
 

generate_docs

@@ -7,13 +7,10 @@ import os
 from pathlib import Path
 from subprocess import CalledProcessError
 
-summary_demarc = '<!-- DO NOT ADD OR CHANGE ANYTHING BELOW THIS LINE -->'
-
-from milc import set_metadata
-
-set_metadata(name='generate_docs', author='MILC', version='1.3.0')
 from milc import cli
 
+cli.milc_options(name='generate_docs', author='MILC', version='1.8.0')
+
 
 @cli.argument('--commit', arg_only=True, action='store_true', help='Commit changes to git.')
 @cli.entrypoint('Generate documentation.')

milc/__init__.py

@@ -18,17 +18,17 @@
 import os
 import sys
 import warnings
-from typing import Optional
+from typing import Any, Optional
 
 from .emoji import EMOJI_LOGLEVELS
-from .milc import MILC
+from .milc_interface import MILCInterface
 
 if 'MILC_IGNORE_DEPRECATED' not in os.environ:
     for name in ('MILC_APP_NAME', 'MILC_APP_VERSION', 'MILC_APP_AUTHOR'):
         if name in os.environ:
-            warnings.warn(f'Using environment variable {name} is deprecated and will not be supported in the future, please use set_metadata() instead.', stacklevel=2)
+            warnings.warn(f'Using environment variable {name} is deprecated and will not be supported in the future, please use cli.milc_options() instead.', stacklevel=2)
 
-cli = MILC()
+cli = MILCInterface()
 
 
 def set_metadata(
@@ -37,21 +37,19 @@ def set_metadata(
     author: Optional[str] = None,
     version: Optional[str] = None,
     logger: Optional[logging.Logger] = None,
-) -> MILC:
+) -> Any:
     """Set metadata about your program.
 
+    Deprecated: Use `cli.milc_options()` instead.
+
     This allows you to set the application's name, version, and/or author
     before executing your entrypoint. You can also pass your own logger here
     if you like.
 
     It's best to run this only once, and it must be run before you call `cli()`.
     """
-    global cli
-
-    if cli._inside_context_manager:
-        raise RuntimeError('You must run set_metadata() before cli()!')
-
-    cli = MILC(name, version, author, logger)
+    warnings.warn("milc.set_metadata has been deprecated, please use cli.milc_options() instead.", stacklevel=2)
+    cli.milc_options(name=name, author=author, version=version, logger=logger)
 
     return cli
 

milc/milc.py

@@ -36,13 +36,7 @@
 class MILC(object):
     """MILC - An Opinionated Batteries Included Framework
     """
-    def __init__(
-        self,
-        name: Optional[str] = None,
-        version: Optional[str] = None,
-        author: Optional[str] = None,
-        logger: Optional[logging.Logger] = None,
-    ) -> None:
+    def __init__(self, name: Optional[str] = None, author: Optional[str] = None, version: Optional[str] = None, logger: Optional[logging.Logger] = None) -> None:
         """Initialize the MILC object.
         """
         # Set some defaults