Merge pull request #22 from ChristianTremblay/release/0.9

Release/0.9

Author: ChristianTremblay

MANIFEST

@@ -43,13 +43,6 @@ pyhaystack\client\ops\vendor\__init__.py
 pyhaystack\client\ops\vendor\niagara.py
 pyhaystack\client\ops\vendor\skyspark.py
 pyhaystack\client\ops\vendor\widesky.py
-pyhaystack\history\HisRecord.py
-pyhaystack\history\__init__.py
-pyhaystack\io\__init__.py
-pyhaystack\io\haystackPoint.py
-pyhaystack\io\haystackRead.py
-pyhaystack\io\jsonParser.py
-pyhaystack\io\zincParser.py
 pyhaystack\server\__init__.py
 pyhaystack\util\__init__.py
 pyhaystack\util\asyncexc.py

README.rst

@@ -35,6 +35,11 @@ As stated in the web site
 
   -- Project-Haystack
 
+New implementation
+--------------------------
+We've been reworking everything from the early version.
+Now, pyhaystack is more robust and will be ready for asynchronous development.
+
 
 .. |build-status| image:: https://travis-ci.org/ChristianTremblay/pyhaystack.svg?branch=master
    :target: https://travis-ci.org/ChristianTremblay/pyhaystack

docs/source/README.rst

@@ -3,14 +3,18 @@ pyhaystack |build-status| |coverage| |docs| |Gitter|
 
 What is this ?
 --------------
-Pyhaystack is a module that allow python programs to connect to a haystack server [project-haystack.org](http://www.project-haystack.org).
+Pyhaystack is a module that allow python programs to connect to a haystack server 
+using semantic data model for buildings (project-haystack_).
+
+Browse a campus, building, floor... find VAV boxes, AHU units, etc. Then extract history 
+data from them and get the results ready for analysis using pandas or your own database implementation.
 
 Which clients are implemented ?
 -------------------------------
 Actually, connection can be established with :
 
 * NiagaraAX_ by Tridium
-* Widesky_ by VRT
+* Widesky_ by VRT_
 * Skyspark_ by SkyFoundry
 
 Connection to Niagara AX requires the nHaystack_ module by J2 Innovations
@@ -21,6 +25,10 @@ How do I install pyhaystack ?
 
     pip install pyhaystack
 
+Or you can also git clone the develop branch and use ::
+
+    python setup.py install
+
 What is project-haystack ?
 --------------------------
 As stated in the web site
@@ -35,6 +43,23 @@ As stated in the web site
 
   -- Project-Haystack
 
+New implementation
+--------------------------
+We've been reworking everything from the early version.
+Now, pyhaystack is more robust and will be ready for asynchronous development.
+
+This new implementation has been mostly supported by VRT_ and Servisys_. We are hoping 
+that more people will join us in our effort to build a well working open-source software
+that will open the door of building data analysis to Python users.
+
+Dependency
+--------------
+Pyhaystack highly depend on hszinc_ which is a special parser for zinc encoded data. 
+Zinc was created for project-haystack_ as a CSV replacement. 
+
+For analysis, we also suggest using Pint_ to deal with units. It will bring a lot of possibilities
+to pyhaystack (ex. unit conversion)
+
 
 .. |build-status| image:: https://travis-ci.org/ChristianTremblay/pyhaystack.svg?branch=master
    :target: https://travis-ci.org/ChristianTremblay/pyhaystack
@@ -56,10 +81,18 @@ As stated in the web site
 
 .. _NiagaraAX : https://www.tridium.com/en/products-services/niagaraax
 
-.. _Widesky : http://www.vrt.com.au/component/energy-efficiency 
+.. _VRT : http://www.vrt.com.au/
+
+.. _Servisys : http://www.servisys.com
+
+.. _Widesky : http://widesky.cloud/ 
 
 .. _nHaystack : https://bitbucket.org/jasondbriggs/nhaystack
 
 .. _project-haystack : http://www.project-haystack.org
 
-..  _Project Haystack : http://www.project-haystack.org
+.. _Project Haystack : http://www.project-haystack.org
+
+.. _Pint : http://pint.readthedocs.io
+
+.. _hszinc : https://github.com/vrtsystems/hszinc

docs/source/conf.py

@@ -41,7 +41,7 @@
     'sphinx.ext.ifconfig',
     'sphinx.ext.viewcode',
 ]
-
+autoclass_content = 'both'
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
@@ -119,7 +119,7 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'bizstyle'
+html_theme = 'sphinx_rtd_theme'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the

docs/source/connect.rst

@@ -8,7 +8,10 @@ Using Niagara AX
     from pyhaystack.client.niagara import NiagaraHaystackSession
     session = NiagaraHaystackSession(uri='http://ip:port', 
                                     username='user', 
-                                    password='myPassword')
+                                    password='myPassword',
+                                    *pint=True)
+
+Note that pint parameter is optionnal and default to False.
 
 Using Widesky
 --------------
@@ -19,7 +22,8 @@ Using Widesky
                                     username='user', 
                                     password='my_password', 
                                     client_id = 'my_id',
-                                    client_secret = 'my_secret')
+                                    client_secret = 'my_secret'
+                                    *pint=True)
  
 
 Using Skyspark
@@ -30,15 +34,16 @@ Using Skyspark
     session = SkysparkHaystackSession(uri='http://ip:port', 
                                     username='user', 
                                     password='my_password', 
-                                    project = 'my_project')
+                                    project = 'my_project'
+                                    *pint=True)
  
-Next
-----
+On-Demand connection
+---------------------
 Once the session is initialized, it won't connect until it needs to.
 Pyhaystack will benefit from the asynchronous framework and connect on demand.
 The session will be connected and the request will be sent to the server.
 
-If when making a request, pyhaystack detects that it has been disconnected, 
+If, when making a request, pyhaystack detects that it has been disconnected, 
 it will re-connect automatically.
 
 See next section to know more about requests.

docs/source/his.rst

@@ -1,13 +1,7 @@
 Histories
 ===================
-Histories (trend) are accessible using 
-`his_read_series(self, point, rng, tz=None,series_format=None, callback=None)` function.
-
-::
-
-    session.his_read('S.SERVISYS.Bureau-Christian.ZN~2dT', rng='today').result
-
-Histories can be retrive as a zinc grid, Pandas series or Pandas Dataframe.
+Histories are a really important part of building data. Pyhaystack allows retrieving histories
+as zinc grid, pandas series or pandas Dataframe depending on your needs.
 
 Range
 +++++
@@ -37,7 +31,6 @@ Retrieve simple grid
     session.his_read('S.SERVISYS.Bureau-Christian.ZN~2dT', rng='today').result
 
 
-
 Retrieve a Pandas Series
 ------------------------
 For more details about Pandas : pandas_datastructure_
@@ -47,13 +40,16 @@ For more details about Pandas : pandas_datastructure_
 
 Retrieve a Pandas Dataframe
 ---------------------------
+In the following example, we will retrive all the historical value from 'today' for
+all zone temperature sensors.
+
 ::
 
     znt = session.find_entity(filter_expr='sensor and zone and temp').result
     b = session.his_read_frame(znt, rng= 'today').result
     b
 
-will return a dataframe of all entities history
+We use ``find_entity`` first, then we call ``his_read_frame`` over the result.
 
 .. _his : http://project-haystack.org/tag/his
 

docs/source/index.rst

@@ -10,13 +10,13 @@ Welcome to pyhaystack's documentation!
 How to use it
 ==================
 .. toctree::
-   :maxdepth: 2
 
   connect
   site
   tags
   his
-  VRT_SERVISYS
+  quantity
+  synchronous
 
 Modules documentation
 =====================

docs/source/pyhaystack.client.entity.mixins.rst

@@ -0,0 +1,46 @@
+pyhaystack.client.entity.mixins package
+=======================================
+
+Submodules
+----------
+
+pyhaystack.client.entity.mixins.equip module
+--------------------------------------------
+
+.. automodule:: pyhaystack.client.entity.mixins.equip
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+pyhaystack.client.entity.mixins.point module
+--------------------------------------------
+
+.. automodule:: pyhaystack.client.entity.mixins.point
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+pyhaystack.client.entity.mixins.site module
+-------------------------------------------
+
+.. automodule:: pyhaystack.client.entity.mixins.site
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+pyhaystack.client.entity.mixins.tz module
+-----------------------------------------
+
+.. automodule:: pyhaystack.client.entity.mixins.tz
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+Module contents
+---------------
+
+.. automodule:: pyhaystack.client.entity.mixins
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/source/pyhaystack.client.entity.models.rst

@@ -0,0 +1,22 @@
+pyhaystack.client.entity.models package
+=======================================
+
+Submodules
+----------
+
+pyhaystack.client.entity.models.haystack module
+-----------------------------------------------
+
+.. automodule:: pyhaystack.client.entity.models.haystack
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+Module contents
+---------------
+
+.. automodule:: pyhaystack.client.entity.models
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/source/pyhaystack.client.entity.ops.rst

@@ -0,0 +1,22 @@
+pyhaystack.client.entity.ops package
+====================================
+
+Submodules
+----------
+
+pyhaystack.client.entity.ops.crud module
+----------------------------------------
+
+.. automodule:: pyhaystack.client.entity.ops.crud
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+Module contents
+---------------
+
+.. automodule:: pyhaystack.client.entity.ops
+    :members:
+    :undoc-members:
+    :show-inheritance: