merge dev into master

.github/PULL_REQUEST_TEMPLATE.md

@@ -7,9 +7,5 @@
 
 **Did you add any tests?**
 
-**Did you check your `pycodestyle`?**
-
 **Are there any special changes in the code that we should be aware of?**
 
-**Are you making a PR to a feature branch or development rather than master?**
-

.gitignore

@@ -85,7 +85,7 @@ endpoints.txt
 .prompt.py.history
 
 preferences.json
-prompt.log
+prompt.log*
 test.log
 
 .pylint

README.md

@@ -20,7 +20,7 @@
   <a href='https://coveralls.io/github/CityOfZion/neo-python?branch=master'>
     <img src='https://coveralls.io/repos/github/CityOfZion/neo-python/badge.svg?branch=master' alt='Coverage Status' />
   </a>
-  
+
 </p>
 
 ## Overview
@@ -33,12 +33,20 @@
 - Interactive CLI for configuring node and inspecting blockchain
 - Runs smart contracts on the blockchain in a Python virtual machine
 - Very basic Wallet functionality (not fully tested, please do not use on mainnet)
+- [NEP2](https://github.com/neo-project/proposals/blob/master/nep-2.mediawiki>) and [NEP5](https://github.com/neo-project/proposals/blob/master/nep-5.mediawiki) compliant wallet functionality
+- RPC Client
+- ``Runtime.Log`` and ``Runtime.Notify`` event monitoring
+
 
 ### What will it do
 
-- Full Python RPC client
-- Compile smart contracts written in Python and deploy them to the blockchain
-- Full smart contract debugging and inspection
+- RPC server
+- Consensus nodes
+- More robust smart contract debugging and inspection
+
+### Documentation
+
+- Installation, Configuration, and usage documentation available at [Read The Docs](https://neo-python.readthedocs.io/en/latest/)
 
 ### Get Help or give help
 
@@ -105,6 +113,13 @@ Then install requirements
 pip install -r requirements.txt
 ```
 
+Finally, install a reference to the `neo` working directory, which allows to `import neo` from
+anywhere in the project (eg. examples):
+```
+pip install -e .
+```
+
+
 ### Installing on OSX
 
 If you're having an issue similar to this:

docs/source/basicusage.rst

@@ -1,11 +1,41 @@
 Basic Usage
 -----------
 
-Start neo-python as follows:
+There are two main ways to use neo-python: ``prompt.py`` and running just the node with custom
+code.
+
+prompt.py
+"""""""""
+
+Start prompt.py on TestNet:
 
 ::
 
-    python neo/prompt.py
+    $ python prompt.py
+
+Show help with all available arguments:
+
+::
+
+    $ python prompt.py -h
+    usage: prompt.py [-h] [-m] [-p] [-c CONFIG] [-t {dark,light}] [--version]
+
+    optional arguments:
+    -h, --help            show this help message and exit
+    -m, --mainnet         Use MainNet instead of the default TestNet
+    -p, --privnet         Use PrivNet instead of the default TestNet
+    -c CONFIG, --config CONFIG
+                            Use a specific config file
+    -t {dark,light}, --set-default-theme {dark,light}
+                            Set the default theme to be loaded from the config
+                            file. Default: 'dark'
+    --version             show program's version number and exit
+
+
 
+Node with custom code
+"""""""""""""""""""""
 
+Take a look at the examples in the ``/examples`` directory: https://github.com/CityOfZion/neo-python/tree/development/examples
 
+See also the sections about "Settings and Logging" and "Interacting with Smart Contracts".

docs/source/contribute.rst

@@ -6,8 +6,8 @@ Help
 ----
 
 -  Open a new `issue`_ if you encounter a problem.
--  Or ping **@localhuman** on the `NEO Slack`_.
--  Pull requests are welcome. New features, writing tests and 
+-  Or ping **@localhuman** or **@metachris** on the `NEO Slack`_.
+-  Pull requests are welcome. New features, writing tests and
    documentation are all needed.
 
 Donations

docs/source/index.rst

@@ -1,3 +1,6 @@
+=======================================================
+neo-python - Python Node and SDK for the NEO blockchain
+=======================================================
 
 .. raw:: html
     <p align="center">
@@ -26,16 +29,18 @@
 
 
 .. toctree::
-    :maxdepth: 10
+    :maxdepth: 2
 
     overview
     install
     basicusage
+    prompt
+    settings-and-logging
+    smartcontracts
     contribute
     license
     tests
-    prompt
 
 .. _issue: https://github.com/CityOfZion/neo-python/issues/new
 .. _NEO Slack: https://join.slack.com/t/neoblockchainteam/shared_invite/MjE3ODMxNDUzMDE1LTE1MDA4OTY3NDQtNTMwM2MyMTc2NA
-.. _MIT: https://github.com/CityOfZion/neo-python/blob/master/LICENSE.md
+.. _MIT: https://github.com/CityOfZion/neo-python/blob/master/LICENSE.md

docs/source/install.rst

@@ -34,9 +34,25 @@ Then install the requirements via
 
     pip install -r requirements.txt
 
-If you plan on doing development, install ``requirements_dev.txt`` instead
 
+Finally, install a reference to the `neo` working directory, in order to be able to `import neo` from
+anywhere in the project (eg. examples):
 
+::
+
+    pip install -e .
+
+
+Updating neo-python from Git
+""""""""""""""""""""""""""""
+
+If you are updating neo-python with ``git pull``, make sure you also update the dependencies with ``pip install -r requirements.txt``.
+
+
+Bootstrapping the Blockchain
+""""""""""""""""""""""""""""
+
+If you use neo-python for the first time, you need to synchronize the blockchain, which may take a long time. Included in this project is ``bootstrap.py`` to automatically download a chain directory for you. To bootstrap for testnet, run ``python bootstrap.py``, get a cup of coffee and wait. To bootstrap for mainnet, use ``python bootstrap.py -m`` and get 8 cups of coffee (3.3 GB file).
 
 
 Platform Specific Instructions
@@ -56,6 +72,7 @@ Ubuntu/Debian
 
     apt-get install libleveldb-dev python3.5-dev python3-pip libssl-dev
 
+
 Centos/Redhat/Fedora
 ^^^^^^^^^^^^^^^^^^^^
 

docs/source/overview.rst

@@ -16,8 +16,8 @@ What does it currently do
 What will it do
 ^^^^^^^^^^^^^^^
 
-- RPC Server
-- Consensus
+- RPC server
+- Consensus nodes
 - Full smart contract debugging and inspection
 
 
@@ -28,3 +28,10 @@ Please follow directions in `the install section <install.html>`_
 The main functionality for this project is contained within the cli application ``prompt.py``.  You can `view usage details here <prompt.html>`_
 
 We have published a Youtube `video <https://youtu.be/oy6Z_zd42-4>`_ to help get you started with this library. There are other videos under the `CityOfZion <(https://www.youtube.com/channel/UCzlQUNLrRa8qJkz40G91iJg>`_ Youtube channel.
+
+
+Sister projects
+^^^^^^^^^^^^^^^
+
+- `neo-python-rpc <https://github.com/CityOfZion/neo-python-rpc>`_: NEO RPC client in Python
+- `neo-boa <https://github.com/CityOfZion/neo-boa>`_: Write smart contracts with Python

docs/source/prompt.rst

@@ -1,9 +1,9 @@
 
 ======
-prompt
+Prompt
 ======
 
-This is the default interface for running and interacting with the NEO blockchain
+This is the default interface for running and interacting with the NEO blockchain.
 
 Usage::
 
@@ -131,6 +131,8 @@ You may want to export a `WIF <https://en.bitcoin.it/wiki/Wallet_import_format>`
 Import NEP2 Passphrase protected WIF
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+You can import a `NEP2 <https://github.com/neo-project/proposals/blob/master/nep-2.mediawiki>`_ encrypted private key like this:
+
 .. code-block:: sh
 
     neo> import nep2 6PYVPVe1fQznphjbUxXP9KZJqPMVnVwCx5s5pr5axRJ8uHkMtZg97eT5kL
@@ -141,6 +143,8 @@ Import NEP2 Passphrase protected WIF
 Export NEP2 Passphrase protected WIF
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+You can export an address as `NEP2 <https://github.com/neo-project/proposals/blob/master/nep-2.mediawiki>`_ encrypted private key like this:
+
 .. code-block:: sh
 
     neo> export nep2 AStZHy8E6StCqYQbzMqi4poH7YNDHQKxvt

docs/source/settings-and-logging.rst

@@ -0,0 +1,104 @@
+Settings and Logging
+====================
+
+neo-python has a settings module which you can use to configure several things:
+
+* The network: MainNet, TestNet, private networks or custom configs
+* Logging:
+ * Smart contract event logging
+ * Logfile (optionally rotating)
+ * Loglevel
+
+To change settings, you have to import the settings instance like this:
+
+::
+
+    from neo.Settings import settings
+
+
+Setting the network
+"""""""""""""""""""
+
+You can use the following settings methods to configure the network:
+
+::
+
+    settings.setup_mainnet()
+    settings.setup_testnet()
+    settings.setup_privnet()
+    settings.setup(config_file)
+
+By default, ``neo-python`` uses the TestNet.
+
+
+Logging
+"""""""
+
+neo-python uses the following defaults:
+
+* all events from all smart contracts are logged with loglevel INFO
+* loglevel is set to INFO
+* logging to a logfile is deactivated (prompt.py logs to prompt.log)
+
+
+Smart Contract Events
+---------------------
+
+If you want to disable logging of all smart contract events, you can do so:
+
+::
+
+    settings.set_log_smart_contract_events(False)
+
+
+Changing the loglevel
+---------------------
+
+To change the loglevel (eg. to also show DEBUG logs, or to only show ERRORS):
+
+::
+
+    import logging
+
+    # Show everything, including debug logs:
+    settings.set_loglevel(logging.DEBUG)
+
+    # Only show errors:
+    settings.set_loglevel(logging.ERROR)
+
+
+Configuring a logfile
+---------------------
+
+To enable logging to a logfile:
+
+::
+
+    # Just a single logfile, with no limits or rotation:
+    settings.set_logfile(your_logfile_path)
+
+    # To enable rotation with a maximum of 10MB per file and 3 rotations:
+    settings.set_logfile(your_logfile_path, 1e7, 3)
+
+
+Logging in custom code
+----------------------
+
+neo-python is using `logzero <https://logzero.readthedocs.io>`_ for logging. To use a
+logger with the existing neo logging configuration, you can just import the logger from logzero:
+
+::
+
+    from logzero import logger
+
+    # These log messages are sent to the console
+    logger.debug("hello")
+    logger.info("info")
+    logger.warn("warn")
+    logger.error("error")
+
+    # This is how you'd log an exception
+    try:
+        raise Exception("this is a demo exception")
+    except Exception as e:
+        logger.exception(e)