Metadata-Version: 2.1
Name: kanjidb
Version: 0.1a2
Summary: Kanji Database
Home-page: https://github.com/Nauja/kanjidb
Author: Jeremy Morosi
Author-email: jeremymorosi@hotmail.com
License: UNKNOWN
Project-URL: Bug Tracker, https://github.com/Nauja/kanjidb/issues
Project-URL: Source Code, https://github.com/Nauja/kanjidb/
Description: # KanjiDB
        
        ![versions](https://img.shields.io/pypi/pyversions/kanjidb.svg)
        [![PyPI version](https://badge.fury.io/py/kanjidb.svg)](https://badge.fury.io/py/kanjidb)
        [![Build Status](https://travis-ci.org/Nauja/kanjidb.png?branch=master)](https://travis-ci.org/Nauja/kanjidb)
        [![Documentation Status](https://readthedocs.org/projects/kanjidb/badge/?version=latest)](https://kanjidb.readthedocs.io/en/latest/?badge=latest)
        [![CircleCI](https://circleci.com/gh/Nauja/kanjidb/tree/circleci-project-setup.svg?style=svg)](https://circleci.com/gh/Nauja/kanjidb/tree/circleci-project-setup)
        [![Test Coverage](https://codeclimate.com/github/Nauja/kanjidb/badges/coverage.svg)](https://codeclimate.com/github/Nauja/kanjidb/coverage)
        [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
        [![contributions welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat)](https://github.com/Nauja/kanjidb/issues)
        
        Kanji database builder and REST API.
        
        KanjiDB aims to help you build your own kanji database by compiling
        informations from various existing source into a single JSON file.
        It's plugin system let you write you own plugin to collect and add new data to kanjis,
        or to arrange already written plugins to meet your needs. It's goal
        is to be flexible enough to let you export all the informations you
        need to build your own app (database, viewer, Anki deck builder, ...) and
        progress in learning Japanese. KanjiDB also comes with a REST API allowing to
        retrieve those informations and build services uppon.
        
        ## Online demo
        
        You can test the REST API online at [kanjidb.jeremymorosi.com/api/v1/doc](http://kanjidb.jeremymorosi.com/api/v1/doc):
        
        ![alt text](http://cdn.jeremymorosi.com/kanjidb/swagger_preview.png "Preview")
        
        The documentation is generated by `aiohttp_swagger`.
        
        ## Install
        
        Using pip:
        
        ```bash
        pip install kanjidb
        ```
        
        Show help:
        
        ```bash
        python -m kanjidb -h
        
        Usage:  kanjidb COMMAND [OPTIONS]
        
        A kanji database accessible via REST API
        
        Options:
          -v, --version            Print version information and quit
          -h, --help               Show this help
        
        Commands:
          build       Build kanji database from sources
          run         Run local server and REST API
        
        Run 'kanjidb COMMAND --help' for more information on a command.
        
        ```
        
        ## Generating a JSON database
        
        Create a `kanjis.txt` file containing one UTF-8 encoded kanji per line. This is the list of kanjis
        that will be included in our database:
        
        ```
        ä¸€
        äºŒ
        ä¸‰
        ```
        
        Now, create a `config.yml` file containing:
        
        ```yaml
        run:
        - kanjidic2:
            kd2_file: path/to/kanjidic2.xml
            inputs:
            - type: stream
              encoding: utf8
              separator: "\n"
              path: path/to/kanjis.txt
            outputs:
            - type: stream
              indent: 4
              path: path/to/db.json
        ```
        
        In this configuration:
          * **kanjistream**: is a plugin that generate a JSON dict with data from a Kanjidic2 XML file.
          * **path/to/kanjidic2.xml**: is the path to a Kanjidic2 XML file ([download here](http://www.edrdg.org/wiki/index.php/KANJIDIC_Project)).
          * **path/to/kanjis.txt**: is the path to the `kanjis.txt` file.
          * **path/to/db.json**: is the destination of generated JSON database.
        
        Run the following command:
        
        ```bash
        python -m kanjidb build config.yml
        ```
        
        This generate a `db.json` file containing the generated JSON database.
        Depending on your configuration this file can be quite big, so here is only an example of what you
        would obtain:
        
        ```json
        {
            "ä¸€": {
                "meanings": [{"m_lang": "", "value": "one"}]
            },
            "äºŒ": {
                "meanings": [{"m_lang": "", "value": "two"}]
            },
            "ä¸‰": {
                "meanings": [{"m_lang": "", "value": "three"}]
            }
        }
        ```
        
        You can read more about the `kanjidic2` plugin and its configuration [here](https://kanjidb.readthedocs.io/en/latest/plugins.html#kanjidic2).
        
        ## Running the REST API
        
        Now we will run a local server with a REST API allowing us to query informations from generated `db.json` file.
        
        First, create a `config.cnf` file containing:
        
        ```ini
        [service]
        port = 8080
        base-url = /api/v1
        swagger-yml = /path/to/swagger.yml
        swagger-url = /api/v1/doc
        db-file = /path/to/db.json
        ```
        
        Just replace:
          * **/path/to/swagger.yml**: by the path to your local [`swagger.yml`](https://github.com/Nauja/kanjidb/blob/master/etc/swagger.yml) file.
          * **/path/to/db.json**: by the path to your generated `db.json` file.
        
        Now run:
        
        ```bash
        python -m kanjidb run /path/to/config.cnf/directory/
        ```
        
        You should see:
        
        ```bash
        ======== Running on http://0.0.0.0:8080 ========
        (Press CTRL+C to quit)
        
        ```
        
        Meaning the service is up and ready.
        
        You can access it via:
         * http://127.0.0.1:8080/api/v1/doc: Swagger documentation
         * http://127.0.0.1:8080/api/v1/kanji: list all kanjis in database.
        
        Note that this repository also include a default `config.cnf`, `swagger.yml` and
        `db.json` file you can use to run the server. Simply checkout this repository and run:
        
        ```bash
        python -m kanjidb run etc
        ```
        
        ## Running with Docker
        
        You can build a Docker image by downloading this repository and running:
        
        ```bash
        docker build -t kanjidb:latest .
        ```
        
        Next, run the Docker image as:
        
        ```bash
        docker run \
         -v /path/to/etc:/etc/service \
         -v /path/to/log:/var/log/service \
         -p 8080:8080 \
         -it kanjidb:latest
        ```
        
        Where:
          * **/path/to/etc**: is the path to the service directory containing **config.cnf**.
          * **/path/to/log**: is the path to the directory where you wan't to store logs.
          * **8080**: is the public port to access the REST API.
        
        You should see:
        
        ```bash
        ======== Running on http://0.0.0.0:8080 ========
        (Press CTRL+C to quit)
        
        ```
        
        Meaning the service is up and ready.
        
        ## Testing
        
        The `test` directory contains many tests that you can run with:
        
        ```python
        python setup.py test
        ```
        
        Or with coverage:
        
        ```python
        coverage run --source=kanjidb setup.py test
        ```
        
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Build Tools
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Requires-Python: >=3.6
Description-Content-Type: text/markdown
