{
    "info": {
        "author": "Georges Bossert",
        "author_email": "gbossert@miskin.fr",
        "bugtrack_url": null,
        "classifiers": [],
        "description": "========================================================================\npylstar : An implementation of the LSTAR Grammatical Inference Algorithm\n========================================================================\n\n.. image:: https://travis-ci.org/gbossert/pylstar.svg?branch=master\n    :target: https://travis-ci.org/gbossert/pylstar\n    :alt: Continuous integration\n\n.. image:: https://coveralls.io/repos/github/gbossert/pylstar/badge.svg?branch=master\n    :target: https://coveralls.io/github/gbossert/pylstar?branch=master\n    :alt: Code coverage\n\n\nAbout pylstar\n=============\n\npylstar is a free and open source Python implementation of the *LSTAR* Grammatical inference algorithm. It can be use to automaticaly infer the state machine that best describe the internal of a deterministic black box. To achieve this, pylstar observes the behavior of the target when stimulated with sequence of messages.\n\nIt has succesfully been used to infer various protocols such as Botnet protocols, Smart Cards protocols, Cryptographic protocols and Web Servers.\n\n\nSample usage\n============\n\nOne that wants to use *pylstar* must write a class that communicates with the targeted black box (*i.e.* it exposes the Minimaly Adequate Teacher of the targeted reactive System). This can be done by subclassing `pylstar.ActiveKnowledgeBase.ActiveKnowledgeBase`. If the targeted process is a network server, one can solely subclass `pylstar.NetworkActiveKnowledgeBase`.\n\nFor example, the following class can be use to start and stop a fake coffee machine (`coffeemachine.py`) through it API (`localhost:3000`). This class inherits from `pylstar.NetworkActiveKnowledgeBase` which exposes methods that can send (and read) network messages to (and by) the coffee machine API.\n\n.. code:: python\n\n    import time\n    import subprocess\n\n    from pylstar.NetworkActiveKnowledgeBase import NetworkActiveKnowledgeBase\n\n    class CoffeeMachineKnowledgeBase(NetworkActiveKnowledgeBase):\n\n        def __init__(self):\n            super(CoffeeMachineKnowledgeBase, self).__init__(\"localhost\", 3000)\n            self.__sp = None\n\n        def start(self):\n        \"\"\"This methods starts the coffee machine (to be triggered before the learning process).\"\"\"\n            self.__sp = subprocess.Popen(\"/usr/bin/python coffeemachine.py\", shell=True)\n            # lets wait 5 seconds for the coffee machine to start\n            time.sleep(5)\n            \n        def stop(self):\n        \"\"\"This method stops the coffee machine (to be triggered after the learning process).\"\"\"\n            if self.__sp is not None:\n                self.__sp.kill()\n\nGiven this wrapper, the following snippet can be used to trigger the automatic inference of the coffee machine. This code declares the messages accepted by the API, an instance of our wrapper and returns a `pylstar.automata.Automata.Automata` (and prints its DOT code) that best describes the behavior of the coffee machine.\n\n.. code:: python\n\n    from pylstar.LSTAR import LSTAR\n    from CoffeeMachineKnowledgeBase import CoffeeMachineKnowledgeBase\n\n    # list of messages accepted by the coffee machine\n    input_vocabulary = [\n        \"REFILL_WATER\",\n        \"REFILL_COFFEE\",\n        \"PRESS_BUTTON_A\",\n        \"PRESS_BUTTON_B\",\n        \"PRESS_BUTTON_C\"    \n    ]\n    # instanciates our CoffeeMachine MAT\n    coffeeBase = CoffeeMachineKnowledgeBase()\n    try:\n        # starts the coffee machine\n        coffeeBase.start()\n        # learns its grammar\n        lstar = LSTAR(input_vocabulary, coffeeBase, max_states = 10)\n        # stores the coffee machine state machine\n        coffee_state_machine = lstar.learn()\n\n        # displays the DOT code of the state machine\n        print(coffee_state_machine.build_dot_code())\n    finally:\n       coffeeBase.stop()\n\nThe execution of this sample returns the state machine illustrated below:\n\n.. image:: https://rawgithub.com/gbossert/pylstar/next/resources/docs/coffee_machine.svg\n    :alt: State Machine of the CoffeeMachine Implementation\n\nA runnable example of the coffee machine inference is available in `test/src/test_pylstar/coffee_machine_example`.\n\nInstallation\n============\n\nPylstar is a typical python library. It relies on a `setup.py` file to describe its installation process.The following command can be use to install pylstar on your system:\n\n.. code:: bash\n\t  \n    $ python setup.py install \n\nMain Features\n=============\n\nPlaying with Automata\n---------------------\n\nThe implementation of automata in pylstar follows the definition of `Mealy Machines <https://en.wikipedia.org/wiki/Mealy_machine>`_. An automaton is made of a unique initial state, states and transitions.\n\nStates\n------\n\nA state (`pylstar.automata.state.State`) is defined by its name (`str`) and some transitions (`list<pylstar.automata.transition.Transition>`). Per default, a state has no transition.\n\n.. code:: python\n\n    from pylstar.automata.State import State\n\n    q0 = State(name=\"Example state\")\n    q1 = State(\"Another state\")\n\nN.B: Two states are said equivalent if their name equals.\n\nTransitions\n-----------\n\nA transition (`pylstar.automata.transition.Transition`) denotes a directed edge between two states. An edge is attached to a source state and is defined by a triplet:\n\n* a name (`str`),\n* an input letter (`pylstar.Letter.Letter`),\n* an output letter (`pylstar.Letter.Letter`),\n* a destination state (`pylstar.automata.State.State`).\n \nThe following snippet defines a transition (`t0`) that can be use to reach \"destination state\" (`q1`) from \"origin state\" (`q0`) if input letter \"a\" (`la`) is received. Executing this transition triggers the emission of letter \"0\" (`l0`).\n\n.. code:: python\n\n    from pylstar.letter import Letter\n    from pylstar.automata.State import State\n    from pylstar.automata.Transition import Transition\n\n    la = Letter(\"a\")\n    l0 = Letter(\"0\")\n    q0 = State(\"origin state\")\n    q1 = State(\"destination state\")\n    t0 = Transition(\"Example Transition\", q1, la, l0) \n    q0.transitions.append(t0)\n\nAutomaton\n---------\n\nAn automaton (`pylstar.automata.Automata.Automata`) is defined by its initial state (`pylstar.automata.State.State`) and an optional name (`str`). For example, the following snippet illustrates the creation of an automaton:\n\n.. code:: python\n\n    from pylstar.automata.Automata import Automata\n    from pylstar.automata.State import State\n\n    q0 = State(name=\"Initial State\")\n    simple_automata = Automata(initial_state = q0, name = \"Simple Automata\")\n\nAn automaton exposes the following methods:\n\n- *build_dot_code()* - Returns the DOT code (`str`) that represents the automaton.\n- *get_states()* - Returns all the states (`list<pylstar.automata.State.State>`) that can be reached from the initial state of the automaton.\n- *play_word(`pylstar.Word.Word` w, `pylstar.automata.State.State` s = None)* - Visits the automaton according to the specified sequence of input messages `w` starting from state `s` (if None, it starts from the initial state). It returns a tupple made of the produced messages and the states reached while visiting the automaton ( `(pylstar.Word.Word, list<pylstar.automata.State.State>)`).\n\n  \nTests\n=====\n\nThis project uses DocTests for testing and documentation purposes.\nTo trigger the tests, please use the following command:\n\n.. code:: bash\n\t  \n    $ python setup.py test\n\n\nReferences\n==========\n\nThe LSTAR algorithm was introduced by Dana Angluin in the article\n\n.. code:: \n\n    @article{Angluin:1987,\n     author = {Angluin, Dana},\n     title = {Learning Regular Sets from Queries and Counterexamples},\n     journal = {Inf. Comput.},\n     issue_date = {November 1, 1987},\n     publisher = {Academic Press, Inc.},\n    } \n\nThis implementation also relies on the description of LSTAR provided by Colin de la Higuera in the book\n\n.. code::\n\n    @book{ColindelaHiguera,\n      author = {de la Higuera, Colin},\n      title = {Grammatical Inference: Learning Automata and Grammars},\n      year = {2010},\n      isbn = {0521763169, 9780521763165},\n      publisher = {Cambridge University Press},\n      address = {New York, NY, USA},\n     }\n\nBugs and enhancements\n=====================\n\nI'm almost certain this code contains bugs. Please, report any bug found by opening a ticket and/or by submiting a pull requests.Obvisouly, the projet is opened to any minor and major enhancements.\n\nAuthor\n======\n\n* Georges Bossert <gbossert@miskin.fr>\n\nLicense\n=======\n\nThis software is licensed under the GPLv3 License. See the ``COPYING.txt`` file\nin the top distribution directory for the full license text.\n    \n\n\nChangelog\n=========\n\n0.1.2 - 2017-10-05\n------------------\n\n    Small bug fixes\n\n0.1.1 - 2017-05-29\n------------------\n\n    Small bug fixes\n\n0.1 - 2017-05-14\n----------------\n\n    Initial version\n\n\nCopyright (C) 2015-2017 Georges Bossert\nCopying and distribution of this file, with or without modification, are\npermitted provided the copyright notice and this notice are preserved.\n",
        "description_content_type": null,
        "docs_url": null,
        "download_url": "https://github.com/gbossert/pylstar",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "https://github.com/gbossert/pylstar",
        "keywords": "LSTAR",
        "license": "GPLv3",
        "maintainer": "",
        "maintainer_email": "",
        "name": "pylstar",
        "package_url": "https://pypi.org/project/pylstar/",
        "platform": "Linux_x86",
        "project_url": "https://pypi.org/project/pylstar/",
        "project_urls": {
            "Download": "https://github.com/gbossert/pylstar",
            "Homepage": "https://github.com/gbossert/pylstar"
        },
        "release_url": "https://pypi.org/project/pylstar/0.1.2/",
        "requires_dist": null,
        "requires_python": "",
        "summary": "Implementation of the LSTAR Grammatical Inference Algorithm",
        "version": "0.1.2"
    },
    "last_serial": 3227860,
    "releases": {
        "0.1": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "5c1380f49f09639c319da3f99a88a4d0",
                    "sha256": "69e6d6888e75d871aa5f8be9b879290e7738d8399880e95c072467f9f980a0f0"
                },
                "downloads": -1,
                "filename": "pylstar-0.1.tar.gz",
                "has_sig": false,
                "md5_digest": "5c1380f49f09639c319da3f99a88a4d0",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 30563,
                "upload_time": "2017-05-29T18:06:31",
                "url": "https://files.pythonhosted.org/packages/22/a9/650abbf5603f72c580e949cd09ff679e2ba67c3d8a32eebbe5aef4224222/pylstar-0.1.tar.gz"
            }
        ],
        "0.1.1": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "38090b883d478e0f48f24d4d89127b01",
                    "sha256": "f775c8d0a573daf3795165bbf8384cc2286d9a593d527ee54b7b8dbbd9665f02"
                },
                "downloads": -1,
                "filename": "pylstar-0.1.1.tar.gz",
                "has_sig": false,
                "md5_digest": "38090b883d478e0f48f24d4d89127b01",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 54092,
                "upload_time": "2017-05-29T21:35:36",
                "url": "https://files.pythonhosted.org/packages/2f/a0/dec1b6db6bdcaf17d8489e9e13f77da3d1355b60341b43bb8184aa69f976/pylstar-0.1.1.tar.gz"
            }
        ],
        "0.1.2": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "827cf3dee43a0409cca5d5a54ef7574b",
                    "sha256": "edd8f6f1628aba5a02a0506046a266c97d81540edaaa9fd9f571a86c52cf07d8"
                },
                "downloads": -1,
                "filename": "pylstar-0.1.2.tar.gz",
                "has_sig": false,
                "md5_digest": "827cf3dee43a0409cca5d5a54ef7574b",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 57082,
                "upload_time": "2017-10-05T12:48:18",
                "url": "https://files.pythonhosted.org/packages/9e/50/a35b29bdaab70c850d41938d53684e233b9803f6305ddd7826484e3a53eb/pylstar-0.1.2.tar.gz"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "827cf3dee43a0409cca5d5a54ef7574b",
                "sha256": "edd8f6f1628aba5a02a0506046a266c97d81540edaaa9fd9f571a86c52cf07d8"
            },
            "downloads": -1,
            "filename": "pylstar-0.1.2.tar.gz",
            "has_sig": false,
            "md5_digest": "827cf3dee43a0409cca5d5a54ef7574b",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 57082,
            "upload_time": "2017-10-05T12:48:18",
            "url": "https://files.pythonhosted.org/packages/9e/50/a35b29bdaab70c850d41938d53684e233b9803f6305ddd7826484e3a53eb/pylstar-0.1.2.tar.gz"
        }
    ]
}