v0.1.0 and docs

.github/ISSUE_TEMPLATE.md

@@ -0,0 +1,12 @@
+**pyheos version with the issue:**
+
+**Python version and environment:**
+
+**Description of problem:**
+
+**Traceback (if applicable):**
+```
+
+```
+
+**Additional information:**

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,11 @@
+## Description:
+<details of changes goes here>
+
+**Related issue (if applicable):** fixes #<pyheos issue number goes here>
+
+## Checklist:
+  - [ ] The code change is tested and works locally.
+  - [ ] Local tests pass with `tox`. **Your PR cannot be merged unless tests pass**
+  - [ ] There is no commented out code in this PR.
+  - [ ] Tests have been added/updated. No exclusions in `.coveragerc` permitted.
+  - [ ] `README.MD` updated (if necessary)

CONTRIBUTING

@@ -0,0 +1,80 @@
+# Contributing Guidelines
+
+Contributions welcome!
+
+**Before spending lots of time on something, ask for feedback on your idea first!**
+
+## Style
+
+This repository follows [PEP8](https://www.python.org/dev/peps/pep-0008/) and [PEP 257 (Docstring Conventions)](https://www.python.org/dev/peps/pep-0257/).  Imports should be sorted with `isort`.  Commits and pull requests are automatically linted with Coveralls, Travis CI, and Hound.
+
+*Save time by checking for style/lint issues **before** committing.*  Run `lint.bat` to automatically install the test dependencies and run the linters.  Alternatively, you can run the linters manually from the root of the project:
+```bash
+pip install isort
+pip install -r test-requirements.txt
+
+isort tests pyheos --recursive
+pylint tests pyheos
+flake8 tests pyheos
+pydocstyle tests pyheos
+```
+
+## Testing
+
+All code is checked to verify:
+- All the unit tests pass
+- All code passes the checks from the linting tools
+- Code coverage is maintained or improved without adding exclusions to `.coveragerc`
+
+You can run all the tests with Tox in a virtual environment by simply running:
+```bash
+tox
+```
+
+Unit tests can be ran outside of Tox by running:
+```bash
+pytest tests
+```
+
+To check the code coverage and determine which statements are not covered, run:
+```bash
+pytest tests --cov --cov-report=term-missing
+```
+
+### Rules
+
+There are a few basic ground-rules for contributors:
+1. Follow the style and testing guidelines above
+2. Fill out the pull request template and complete check-list activities
+3. Submit a pull request and be responsive to questions and feedback
+
+### Releases
+
+Declaring formal releases remains the prerogative of the project maintainer.
+
+### Changes to this arrangement
+
+This is an experiment and feedback is welcome! This document may also be subject to pull-
+requests or changes by contributors where you believe you have something valuable to add
+or change.
+
+## Developer's Certificate of Origin 1.1
+
+By making a contribution to this project, I certify that:
+
+- (a) The contribution was created in whole or in part by me and I have the right to
+  submit it under the open source license indicated in the file; or
+
+- (b) The contribution is based upon previous work that, to the best of my knowledge, is
+  covered under an appropriate open source license and I have the right under that license
+  to submit that work with modifications, whether created in whole or in part by me, under
+  the same open source license (unless I am permitted to submit under a different
+  license), as indicated in the file; or
+
+- (c) The contribution was provided directly to me by some other person who certified
+  (a), (b) or (c) and I have not modified it.
+
+- (d) I understand and agree that this project and the contribution are public and that a
+  record of the contribution (including all personal information I submit with it,
+  including my sign-off) is maintained indefinitely and may be redistributed consistent
+  with this project or the open source license(s) involved.

README.md

@@ -6,4 +6,45 @@
 [![image](https://img.shields.io/pypi/l/pyheos.svg)](https://pypi.org/project/pyheos/)
 [![image](https://img.shields.io/badge/Reviewed_by-Hound-8E64B0.svg)](https://houndci.com)
 
-A python based library for interacting with HEOS devices using the CLI and asyncio.  Work in progress.
+An async python library for controlling HEOS devices through the HEOS CLI Protocol (version 1.13 for players with firmware 1.481.130 or newer).
+
+## Installation
+```bash
+pip install pyheos
+```
+or
+```bash
+pip install --use-wheel pyheos
+```
+
+## Getting Started
+
+The `Heos` class is the implementation providing control to all HEOS compatible devices on the local network through a single network connection.  It is suggested to connect to a device that is hard-wired.
+
+#### `pyheos.Heos(host, *, timeout, heart_beat, all_progress_events, dispatcher)`
+- `host: str`: The IP Address or hostname of a HEOS device on the local network. This parameter is required.
+- `timeout: float`: Number of seconds to wait during connection and issuing commands. Default is `pyheos.const.DEFAULT_TIMEOUT = 5.0`.  This parameter is required.
+- `heart_beat: Optional[float]`: Number of seconds since last activity to issue a heart-beat command. Default is `pyheos.const.DEFAULT_HEART_BEAT = 60.0`.  Set this parameter to `None` to disable heart-beat.
+- `all_progress_events`: Set to `True` to receive signals for each media play-back progression or `False` to only receive a signal when media state transitions to playing or changes.  Defualt is `True`.  This parameter is required.
+- `dispatcher: Optional[pyheos.Dispatcher]`: An instance of dispatcher to use for raising signals.  The default is `None` which results in use of he default dispatcher implementation.
+
+#### `pyheos.Heos.connect(*, auto_reconnect, reconnect_delay)`
+
+Connect to the specified host.  This method is a coroutine.
+- `auto_reconnect: bool`: Set to `True` to automatically reconnect to the host upon disconnection.  The default is `False`.
+- `reconnect_delay: float`: The number of seconds to wait before attempting to reconnect upon a connection failure. The default is `DEFAULT_RECONNECT_DELAY = 5.0`
+
+#### `pyheos.Heos.disconnect()`
+
+Disconnect from the specified host.  This method is a coroutine.
+
+##### Example:
+```python
+import pyheos
+
+heos = Heos('172.16.0.1')
+
+await heos.connect(auto_reconnect=True)
+...
+await heos.disconnect()
+```

pyheos/__init__.py

@@ -1,8 +1,17 @@
 """pyheos - a library for interacting with HEOS devices."""
 
+from . import const
+from .dispatch import Dispatcher
 from .heos import Heos
+from .player import HeosNowPlayingMedia, HeosPlayer
+from .source import HeosSource, InputSource
 
 __all__ = [
-    # heos
-    'Heos'
+    'const',
+    'Dispatcher',
+    'Heos',
+    'HeosPlayer',
+    'HeosNowPlayingMedia',
+    'HeosSource',
+    'InputSource'
 ]

pyheos/const.py

@@ -1,7 +1,7 @@
 """Define consts for the pyheos package."""
 
 __title__ = "pyheos"
-__version__ = "0.0.1"
+__version__ = "0.1.0"
 
 CLI_PORT = 1255
 DEFAULT_TIMEOUT = 5.0

setup.py

@@ -15,7 +15,7 @@
 
 setup(name=const['__title__'],
       version=const['__version__'],
-      description='A python library for interacting with HEOS devices using the CLI and asyncio.',
+      description='An async python library for controlling HEOS devices through the HEOS CLI Protocol',
       long_description=long_description,
       long_description_content_type='text/markdown',
       url='https://github.com/andrewsayre/pyheos',

test-requirements.txt

@@ -1,4 +1,4 @@
-coveralls==1.6.0
+coveralls==1.7.0
 flake8==3.7.7
 flake8-docstrings==1.3.0
 pydocstyle==3.0.0