First release

Author: JS5391

.gitignore

@@ -0,0 +1 @@
+/.idea/

.pre-commit-config.yaml

@@ -0,0 +1,5 @@
+repos:
+  - repo: https://github.com/psf/black
+    rev: 20.8b1
+    hooks:
+      - id: black

.travis.yml

@@ -0,0 +1,16 @@
+language: python
+python:
+  - "3.6"
+  - "3.7"
+  - "3.8"
+  - "3.9-dev"
+install:
+  - pip install .[testing]
+script:
+  - pytest --cov=logging_json --cov-fail-under=100
+deploy:
+  provider: pypi
+  username: __token__
+  edge: true
+  distributions: "sdist bdist_wheel"
+  skip_existing: true

CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.0.1] - 2020-10-15
+### Added
+- Public release.
+
+[Unreleased]: https://github.com/Colin-b/healthpy/compare/v0.0.1...HEAD
+[0.0.1]: https://github.com/Colin-b/healthpy/releases/tag/v0.0.1

CONTRIBUTING.md

@@ -0,0 +1,73 @@
+# How to contribute
+
+Everyone is free to contribute on this project.
+
+There are 2 ways to contribute:
+
+- [Submit an issue.](#submitting-an-issue)
+- [Submit a pull request.](#submitting-a-pull-request)
+
+## Submitting an issue
+
+Before creating an issue please make sure that it was not already reported.
+
+### When?
+
+- You encountered an issue.
+- You have a change proposal.
+- You have a feature request.
+
+### How?
+
+1) Go to the *Issues* tab and click on the *New issue* button.
+2) Title should be a small sentence describing the request.
+3) The comment should contains as much information as possible
+    * Actual behavior (including the version you used)
+    * Expected behavior
+    * Steps to reproduce
+
+## Submitting a pull request
+
+### When?
+
+- You fixed an issue.
+- You changed something.
+- You added a new feature.
+
+### How?
+
+#### Code
+
+1) Create a new branch based on `develop` branch.
+2) Fetch all dev dependencies.
+    * Install required python modules using [`pip`](https://pypi.org/project/pip/): **python -m pip install .[testing]**
+3) Ensure tests are ok by running them using [`pytest`](http://doc.pytest.org/en/latest/index.html).
+4) Follow [Black](https://black.readthedocs.io/en/stable/) code formatting.
+    * Install [pre-commit](https://pre-commit.com) python module using pip: **python -m pip install pre-commit**
+    * To add the [pre-commit](https://pre-commit.com) hook, after the installation run: **pre-commit install**
+5) Add your changes.
+    * The commit should only contain small changes and should be atomic.
+    * The commit message should follow [those rules](https://chris.beams.io/posts/git-commit/).
+6) Add or update at least one [`pytest`](http://doc.pytest.org/en/latest/index.html) test case.
+    * Unless it is an internal refactoring request or a documentation update.
+    * Each line of code should be covered by the test cases.
+7) Add related [changelog entry](https://keepachangelog.com/en/1.1.0/) in the Unreleased section.
+    * Unless it is a documentation update.
+
+#### Enter pull request
+
+1) Go to the *Pull requests* tab and click on the *New pull request* button.
+2) *base* should always be set to `develop` and it should be compared to your branch.
+3) Title should be a small sentence describing the request.
+4) The comment should contains as much information as possible
+    * Actual behavior (before the new code)
+    * Expected behavior (with the new code)
+5) A pull request can contain more than one commit, but the entire content should still be [atomic](#what-is-an-atomic-pull-request).
+
+##### What is an atomic pull request
+
+It is important for a Pull Request to be atomic. But with a Pull Request, we measure the "succeed" as the ability to deliver the smallest possible piece of functionality, it can either be composed by one or many atomic commits.
+
+One of the bad practices of a Pull Request is changing things that are not concerned with the functionality that is being addressed, like whitespace changes, typo fixes, variable renaming, etc. If those things are not related to the concern of the Pull Request, it should probably be done in a different one.
+
+One might argue that this practice of not mixing different concerns and small fixes in the same Pull Request violates the Boy Scout Rule because it doesn't allow frequent cleanup. However, cleanup doesn't need to be done in the same Pull Request, the important thing is not leaving the codebase in a bad state after finishing the functionality. If you must, refactor the code in a separate Pull Request, and preferably before the actually concerned functionality is developed, because then if there is a need in the near future to revert the Pull Request, the likelihood of code conflict will be lower. [source](https://medium.com/@fagnerbrack/one-pull-request-one-concern-e84a27dfe9f1)

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 Colin Bounouar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,152 @@
+<h2 align="center">JSON formatter for logging</h2>
+
+<p align="center">
+<a href="https://pypi.org/project/logging_json/"><img alt="pypi version" src="https://img.shields.io/pypi/v/logging_json"></a>
+<a href="https://travis-ci.com/Colin-b/logging_json"><img alt="Build status" src="https://api.travis-ci.com/Colin-b/logging_json.svg?branch=master"></a>
+<a href="https://travis-ci.com/Colin-b/logging_json"><img alt="Coverage" src="https://img.shields.io/badge/coverage-100%25-brightgreen"></a>
+<a href="https://github.com/psf/black"><img alt="Code style: black" src="https://img.shields.io/badge/code%20style-black-000000.svg"></a>
+<a href="https://travis-ci.com/Colin-b/logging_json"><img alt="Number of tests" src="https://img.shields.io/badge/tests-0 passed-blue"></a>
+<a href="https://pypi.org/project/logging_json/"><img alt="Number of downloads" src="https://img.shields.io/pypi/dm/logging_json"></a>
+</p>
+
+This module provides a JSON formatter for the python [`logging`](https://docs.python.org/3/library/logging.html) module.
+
+## Features
+
+### Adding additional fields and values
+
+You can add fields to every message that is being logged.
+To do so, specify the `fields` parameter to the `logging_json.JSONFormatter` instance.
+
+It must be a dictionary where keys are the keys to be appended to the resulting JSON dictionary (if not already present) and the values can be one of the following:
+* An attribute of the logging record (non-exhaustive list can be found on [the python logging documentation](https://docs.python.org/3/library/logging.html#logrecord-attributes)).
+* If not found on the record, the value will be linked to the key.
+
+#### Logging exceptions, a specific case
+
+If an exception is loggued, the `exception` key will be appended to the resulting JSON dictionary.
+
+This dictionary will contains 3 keys:
+* `type`: The name of the exception class (useful when the message is blank).
+* `message`: The str representation of the exception (usually the provided error message).
+* `stack`: The stack trace, formatted as a string.
+
+### Logging with a dictionary
+
+This formatter allows you to log dictionary as in the following:
+
+```python
+import logging
+
+logging.info({"key": "value", "other key": "other value"})
+```
+
+The resulting JSON dictionary will be the one you provided (with the [additional fields](#adding-additional-fields-and-values)).
+
+### Logging with anything else (such as a string)
+
+Anything not logged using a dictionary will be handled by the standard formatter and it can result in one of the 2 output:
+* A JSON dictionary, if [additional fields](#adding-additional-fields-and-values) are set, with the message available in the `msg` key of the resulting JSON dictionary.
+* The formatted record, if no [additional fields](#adding-additional-fields-and-values) are set. 
+
+This handles the usual string logging as in the following:
+
+```python
+import logging
+
+logging.info("This is my message")
+```
+
+## Configuration
+
+You can create a formatter instance yourself as in the following or you can use a logging configuration.
+
+```python
+import logging_json
+
+formatter = logging_json.JSONFormatter(fields={
+    "level_name": "levelname",
+    "thread_name": "threadName",
+    "process_name": "processName"
+})
+```
+
+### Using logging.config.dictConfig
+
+You can configure your logging as advertise by python, by using the `logging.config.dictConfig` function.
+
+#### dict configuration
+
+```python
+import logging.config
+import logging_json
+import sys
+
+formatter = logging_json.JSONFormatter(fields={
+    "level_name": "levelname",
+    "thread_name": "threadName",
+    "process_name": "processName"
+})
+handler = logging.StreamHandler(stream=sys.stdout)
+handler.setFormatter(formatter)
+
+logging.config.dictConfig({
+    "version": 1,
+    "formatters": {
+        "json": formatter
+    },
+    "handlers": {
+        "standard_output": handler,
+    },
+    "loggers": {
+        "my_app": {"level": "DEBUG"}
+    },
+    "root": {
+        "level": "INFO",
+        "handlers": ["standard_output"]
+    }
+})
+```
+
+#### YAML logging configuration
+
+You can use YAML to store your logging configuration, as in the following sample:
+
+```python
+import logging.config
+import yaml
+
+with open("path/to/logging_configuration.yaml", "r") as config_file:
+    logging.config.dictConfig(yaml.load(config_file))
+```
+
+Where `logging_configuration.yaml` can be a file containing the following sample:
+
+```yaml
+version: 1
+formatters:
+  json:
+    '()': logging_json.JSONFormatter
+    fields:
+      level_name: levelname
+      thread_name: threadName
+      process_name: processName
+handlers:
+  standard_output:
+    class: logging.StreamHandler
+    formatter: json
+    stream: ext://sys.stdout
+loggers:
+  my_app:
+    level: DEBUG
+root:
+  level: INFO
+  handlers: [standard_output]
+```
+
+## How to install
+1. [python 3.6+](https://www.python.org/downloads/) must be installed
+2. Use pip to install module:
+```sh
+python -m pip install logging_json
+```

_config.yml

@@ -0,0 +1 @@
+theme: jekyll-theme-cayman

logging_json/__init__.py

@@ -0,0 +1,2 @@
+from logging_json.version import __version__
+from logging_json._formatter import JSONFormatter

logging_json/_formatter.py

@@ -0,0 +1,54 @@
+import collections
+import json
+import logging
+from typing import Any
+
+
+def _value(record: logging.LogRecord, field_name_or_value: Any) -> Any:
+    """
+    Retrieve value from record if possible. Otherwise use value.
+    :param record: The record to extract a field named as in field_name_or_value.
+    :param field_name_or_value: The field name to extract from record or the default value to use if not present.
+    """
+    try:
+        return getattr(record, field_name_or_value)
+    except:
+        return field_name_or_value
+
+
+class JSONFormatter(logging.Formatter):
+    def __init__(self, *args, fields=None, **kwargs):
+        # Allow to provide any formatter setting (useful to provide a custom date format)
+        super().__init__(*args, **kwargs)
+        self.fields = fields or {}
+        self.usesTime = lambda: "asctime" in self.fields.values()
+
+    def format(self, record: logging.LogRecord):
+        # Let python set every additional record field
+        super().format(record)
+
+        message = {
+            field_name: _value(record, field_value)
+            for field_name, field_value in self.fields.items()
+        }
+        if isinstance(record.msg, collections.abc.Mapping):
+            message.update(record.msg)
+        else:
+            message["msg"] = super().formatMessage(record)
+
+        if record.exc_info:
+            message["exception"] = {
+                "type": record.exc_info[0].__name__,
+                "message": str(record.exc_info[1]),
+                "stack": self.formatException(record.exc_info),
+            }
+
+        return (
+            super().formatMessage(record)
+            if (len(message) == 1 and "msg" in message)
+            else json.dumps(message)
+        )
+
+    def formatMessage(self, record: logging.LogRecord) -> str:
+        # Speed up this step by doing nothing
+        return ""