add k3log

.gift-refs

@@ -1,2 +1,2 @@
 - - _building
-  - e46e6dbad26ee29fe830c9ec9fb83d448db74daf
+  - 7727d998036b834fe86d1e995107f42c7fd25276

.github/settings.yml

@@ -1,6 +1,6 @@
 _extends: gh-config
 
 repository:
-  description: no desc
+  description: k3log is a collection of log utilities.
   homepage: https://blog.openacid.com
-  topics: tag1, tag2
+  topics: logging, stack

.travis.yml

@@ -17,14 +17,11 @@ script:
     - sudo env "PATH=$PATH" python -c 'import sys; print(sys.version)'           # environment check
     - sudo env "PATH=$PATH" python -c 'import sys; print(sys.version_info)'           # environment check
 
-    # Some tests do not pass on travis-ci.
-    # E.g.: redis, mysql, zookeeper, etcd needs a docker to test.
-    # Disable them temporarily.
-    # -- by xp 2020 Jan 27
-
     # Enable debug log: UT_DEBUG=1
     - >-
         sudo env "PATH=$PATH" UT_DEBUG=0 PYTHONPATH="$(cd ..; pwd)" python -m unittest discover -c --failfast -s .
 
+    - make -C docs html
+
 # after_success:
 #   - pip install python-coveralls && coveralls

README.md

@@ -1,29 +1,39 @@
-# pk3proc
+# k3log
 
-[![Build Status](https://travis-ci.com/pykit3/pk3proc.svg?branch=master)](https://travis-ci.com/pykit3/pk3proc)
-[![Documentation Status](https://readthedocs.org/projects/pk3proc/badge/?version=stable)](https://pk3proc.readthedocs.io/en/stable/?badge=stable)
+[![Build Status](https://travis-ci.com/pykit3/k3log.svg?branch=master)](https://travis-ci.com/pykit3/k3log)
+[![Documentation Status](https://readthedocs.org/projects/k3log/badge/?version=stable)](https://k3log.readthedocs.io/en/stable/?badge=stable)
+[![Package](https://img.shields.io/pypi/pyversions/k3log)](https://pypi.org/project/k3log)
+
+k3log is a collection of log utilities.
+
+k3log is a component of [pykit3] project: a python3 toolkit set.
 
-no desc
 
 # Install
 
 ```
-pip install pk3proc
+pip install k3log
 ```
 
 # Synopsis
 
 ```python
-import pk3proc
-
-# execute a shell script
-returncode, out, err = pk3proc.shell_script('ls / | grep bin')
-print returncode
-print out
-# output:
-# > 0
-# > bin
-# > sbin
+
+# make a file logger in one line
+logger = pk3logutil.make_logger('/tmp', level='INFO', fmt='%(message)s',
+                                datefmt="%H:%M:%S")
+logger.info('foo')
+
+logger.stack_str(fmt="{fn}:{ln} in {func}\n  {statement}", sep="\n")
+# runpy.py:174 in _run_module_as_main
+#   "__main__", fname, loader, pkg_name)
+# runpy.py:72 in _run_code
+#   exec code in run_globals
+# ...
+# test_logutil.py:82 in test_deprecate
+#   pk3logutil.deprecate()
+#   'foo', fmt='{fn}:{ln} in {func}\n  {statement}', sep='\n')
+
 ```
 
 #   Author
@@ -34,4 +44,7 @@ Zhang Yanpo (张炎泼) <drdr.xp@gmail.com>
 
 The MIT License (MIT)
 
-Copyright (c) 2015 Zhang Yanpo (张炎泼) <drdr.xp@gmail.com>
+Copyright (c) 2015 Zhang Yanpo (张炎泼) <drdr.xp@gmail.com>
+
+
+[pykit3]: https://github.com/pykit3

__init__.py

@@ -1,29 +1,43 @@
 """
-package-name is utility to create sub process.
-
-Execute a shell script::
-
-    import pk3proc
-
-    # execute a shell script
-
-    returncode, out, err = pk3proc.shell_script('ls / | grep bin')
-    print returncode
-    print out
-    # output:
-    # > 0
-    # > bin
-    # > sbin
-
-Run a command::
-
-    # Unlike the above snippet, following statement does not start an sh process.
-    returncode, out, err = pk3proc.command('ls', 'a*', cwd='/usr/local')
-
+k3log is a collection of log utilities for logging.
 """
 
-# from .proc import CalledProcessError
-# from .proc import ProcError
-
-__version__ = "0.2.2"
-_name = "pk3proc"
+from .log import (
+    add_std_handler,
+    deprecate,
+    get_datefmt,
+    get_fmt,
+    get_root_log_fn,
+    make_file_handler,
+    make_formatter,
+    make_logger,
+    set_logger_level,
+    stack_format,
+    stack_list,
+    stack_str,
+)
+
+#  from .archive import(
+#      Archiver,
+
+#      archive,
+#      clean,
+#  )
+
+__version__ = "0.1.2"
+__name__ = "k3log"
+
+__all__ = [
+    "add_std_handler",
+    "deprecate",
+    "get_datefmt",
+    "get_fmt",
+    "get_root_log_fn",
+    "make_file_handler",
+    "make_formatter",
+    "make_logger",
+    "set_logger_level",
+    "stack_format",
+    "stack_list",
+    "stack_str",
+]

_building/README.md.j2

@@ -2,9 +2,13 @@
 
 [![Build Status](https://travis-ci.com/pykit3/{{ name }}.svg?branch=master)](https://travis-ci.com/pykit3/{{ name }})
 [![Documentation Status](https://readthedocs.org/projects/{{ name }}/badge/?version=stable)](https://{{ name }}.readthedocs.io/en/stable/?badge=stable)
+[![Package](https://img.shields.io/pypi/pyversions/{{ name }})](https://pypi.org/project/{{ name }})
 
 {{ description }}
 
+{{ name }} is a component of [pykit3] project: a python3 toolkit set.
+
+
 # Install
 
 ```
@@ -14,7 +18,7 @@ pip install {{ name }}
 # Synopsis
 
 ```python
-{% include 'example.py' %}
+{{ synopsis }}
 ```
 
 #   Author
@@ -26,3 +30,6 @@ Zhang Yanpo (张炎泼) <drdr.xp@gmail.com>
 The MIT License (MIT)
 
 Copyright (c) 2015 Zhang Yanpo (张炎泼) <drdr.xp@gmail.com>
+
+
+[pykit3]: https://github.com/pykit3

_building/__init__.py

@@ -59,7 +59,8 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+# html_static_path = ['_static']
+html_static_path = []
 
 
 def sphinx_confs(name):

_building/build_readme.py

@@ -1,19 +1,27 @@
 #!/usr/bin/env python
 # coding: utf-8
 
-import os
+import doctest
 import imp
-import yaml
+import os
+import sys
+
 import jinja2
+import yaml
 
 # xxx/_building/build_readme.py
 this_base = os.path.dirname(__file__)
 
 j2vars = {}
 
+# let it be able to find indirectly dependent package locally
+# e.g.: `k3fs` depends on `k3confloader`
+sys.path.insert(0, os.path.abspath('..'))
+
 # load package name from __init__.py
 pkg = imp.load_source("_foo", '__init__.py')
-j2vars["name"] = pkg._name
+j2vars["name"] = pkg.__name__
+
 
 def get_gh_config():
     with open('.github/settings.yml', 'r') as f:
@@ -25,9 +33,38 @@ def get_gh_config():
     cfg['repository']['topics'] = tags
     return cfg
 
+
 cfg = get_gh_config()
 j2vars['description'] = cfg['repository']['description']
 
+
+def get_examples(pkg):
+    doc = pkg.__doc__
+    parser = doctest.DocTestParser()
+    es = parser.get_examples(doc)
+    rst = []
+    for e in es:
+        rst.append('>>> ' + e.source.strip())
+        rst.append(e.want.strip())
+
+    rst = '\n'.join(rst)
+
+    for fn in ("synopsis.txt",
+               "synopsis.py",
+               ):
+        try:
+            with open(fn, 'r') as f:
+                rst += '\n' + f.read()
+
+        except FileNotFoundError:
+            pass
+
+    return rst
+
+
+j2vars['synopsis'] = get_examples(pkg)
+
+
 def render_j2(tmpl_path, tmpl_vars, output_path):
     template_loader = jinja2.FileSystemLoader(searchpath='./')
     template_env = jinja2.Environment(loader=template_loader,
@@ -39,7 +76,8 @@ def render_j2(tmpl_path, tmpl_vars, output_path):
     with open(output_path, 'w') as f:
         f.write(txt)
 
+
 if __name__ == "__main__":
     render_j2('_building/README.md.j2',
-       j2vars,
-       'README.md')
+              j2vars,
+              'README.md')

docs/source/conf.py

@@ -3,7 +3,15 @@
 
 sys.path.insert(0, os.path.abspath('../..'))
 
-import _building
+# In order to find indirect dependency
+sys.path.insert(0, os.path.abspath('../../..'))
+
+# use a try to force not to reorder sys.path and import.
+try:
+    import _building
+except Exception as e:
+    raise e
+
 
 (project,
  pkg,
@@ -17,4 +25,4 @@
  master_doc,
  html_theme,
  html_static_path,
-) = _building.sphinx_confs("this-package")
+ ) = _building.sphinx_confs("this-package")

docs/source/index.rst

@@ -1,12 +1,14 @@
-.. this-package documentation master file, created by
+.. k3log documentation master file, created by
    sphinx-quickstart on Thu May 14 16:58:55 2020.
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-this-package
+k3log
 ==========
 
-pykit3 is is a collection of toolkit in python3.
+.. automodule:: k3log
+
+.. literalinclude:: ../../synopsis.py
 
 .. toctree::
    :maxdepth: 2
@@ -15,24 +17,21 @@ pykit3 is is a collection of toolkit in python3.
 Documentation for the Code
 **************************
 
-.. automodule:: this-package
-
-
-Exceptions
-----------
-
-.. autoexception::  CalledProcessError
-.. autoexception::  ProcError
-.. autoexception::  TimeoutExpired
-
-
 Functions
 ---------
 
-.. autofunction::  command
-.. autofunction::  command_ex
-.. autofunction::  shell_script
-.. autofunction::  start_process
+.. autofunction::  add_std_handler
+.. autofunction::  deprecate
+.. autofunction::  get_datefmt
+.. autofunction::  get_fmt
+.. autofunction::  get_root_log_fn
+.. autofunction::  make_file_handler
+.. autofunction::  make_formatter
+.. autofunction::  make_logger
+.. autofunction::  set_logger_level
+.. autofunction::  stack_format
+.. autofunction::  stack_list
+.. autofunction::  stack_str
 
 Indices and tables
 ==================