From 396224045b5a9b69391bbb26bb833110a5033422 Mon Sep 17 00:00:00 2001 From: Marcelo Moreira de Mello Date: Mon, 24 Jul 2017 02:13:12 -0400 Subject: [PATCH] version 1.2.1 (#81) * Added documentation * Fixed typo * Exclude flake8 from docs directory * Added as_dict() method to Amcrest object (#80) Fixes issue# https://github.com/home-assistant/home-assistant/issues/8551 * Complements commit ae3cd8f90d2ca2c7f8f2155191efb6c62cd828df * Bump dev version 1.2.1 * Fix houndci-bot and bump version on autogen file --- README.rst | 2 + configure.ac | 2 +- docs/Makefile | 20 ++++ docs/conf.py | 161 ++++++++++++++++++++++++++++++ docs/index.rst | 231 ++++++++++++++++++++++++++++++++++++++++++++ docs/make.bat | 36 +++++++ setup.py | 2 +- src/amcrest/http.py | 6 ++ tox.ini | 1 + 9 files changed, 459 insertions(+), 2 deletions(-) create mode 100644 docs/Makefile create mode 100644 docs/conf.py create mode 100644 docs/index.rst create mode 100644 docs/make.bat diff --git a/README.rst b/README.rst index 50c474c..5aaa701 100644 --- a/README.rst +++ b/README.rst @@ -16,6 +16,8 @@ Python Amcrest A Python 2.7/3.x module for `Amcrest Cameras `_ using the SDK HTTP API. +Documentation: `http://python-amcrest.readthedocs.io/ `_ + ------------ Installation ------------ diff --git a/configure.ac b/configure.ac index f50fd4f..a4ec309 100644 --- a/configure.ac +++ b/configure.ac @@ -10,7 +10,7 @@ # GNU General Public License for more details. define([VERSION_MAJOR], [1]) define([VERSION_MINOR], [2]) -define([VERSION_FIX], [0]) +define([VERSION_FIX], [1]) define([VERSION_NUMBER], VERSION_MAJOR[.]VERSION_MINOR[.]VERSION_FIX) define([VERSION_SUFFIX], [_master]) diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..f964381 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = python -msphinx +SPHINXPROJ = PythonAmcrest +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..9915d2e --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,161 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +# +# Python Amcrest documentation build configuration file, created by +# sphinx-quickstart on Fri Jun 2 01:30:31 2017. +# +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = ['sphinx.ext.autodoc', + 'sphinx.ext.doctest', + 'sphinx.ext.intersphinx', + 'sphinx.ext.coverage', + 'sphinx.ext.viewcode'] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +# source_suffix = ['.rst', '.md'] +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = 'Python Amcrest' +copyright = '2017, Douglas Schilling Landgraf, Marcelo Moreira de Mello' +author = 'Douglas Schilling Landgraf, Marcelo Moreira de Mello' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '' +# The full version, including alpha/beta/rc tags. +release = '' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This patterns also effect to html_static_path and html_extra_path +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = False + + +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'alabaster' + +# 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 +# documentation. +# +# html_theme_options = {} + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['.'] + + +# -- Options for HTMLHelp output ------------------------------------------ + +# Output file base name for HTML help builder. +htmlhelp_basename = 'PythonAmcrestdoc' + + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'PythonAmcrest.tex', 'Python Amcrest Documentation', + 'Douglas Schilling Landgraf, Marcelo Moreira de Mello', 'manual'), +] + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'pythonamcrest', 'Python Amcrest Documentation', + [author], 1) +] + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'PythonAmcrest', 'Python Amcrest Documentation', + author, 'PythonAmcrest', 'One line description of project.', + 'Miscellaneous'), +] + +# Example configuration for intersphinx: refer to the Python standard library. +intersphinx_mapping = {'https://docs.python.org/': None} diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..f6d439d --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,231 @@ +.. Python Amcrest documentation master file, created by + sphinx-quickstart on Fri Jun 2 01:30:31 2017. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to Python Amcrest's documentation! +========================================== + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + +A Python 2.7/3.x module for `Amcrest Cameras `_ using the SDK HTTP API. + +------------ +Installation +------------ + +PyPI +---- + +.. code-block:: bash + + $ pip install amcrest --upgrade + $ eval "$(register-python-argcomplete amcrest-cli)" + + # To enable amcrest-cli autocomplete in the system: + $ echo 'eval "$(register-python-argcomplete amcrest-cli)"' > /etc/profile.d/amcrest-cli-autocomplete.sh + +RPM +--- + +.. code-block:: bash + + $ git clone git@github.com:tchellomello/python-amcrest.git + $ ./autogen.sh + $ make rpm + $ dnf/yum install amcrest-cli-NVR.rpm pythonX-amcrest-NVR.rpm + + +----- +Usage +----- + +.. code-block:: python + + from amcrest import AmcrestCamera + camera = AmcrestCamera('192.168.0.1', 80, 'admin', 'password').camera + + #Check software information + camera.software_information + 'version=2.420.AC00.15.R\r\nBuildDate=2016-09-08' + + #Capture snapshot + camera.snapshot(0, "/home/user/Desktop/snapshot00.jpeg") + + + #Capture audio + camera.audio_stream_capture(httptype="singlepart", channel=1, path_file="/home/user/Desktop/audio.aac") + CTRL-C to stop the continuous audio flow or use a timer + + #Move camera down + camera.ptz_control_command(action="start", code="Down", arg1=0, arg2=0, arg3=0))) + + #Record realtime stream into a file + camera.realtime_stream(path_file="/home/user/Desktop/myvideo") + CTRL-C to stop the continuous video flow or use a timer + +Command Line +------------ + +.. code-block:: bash + + $ man amcrest-cli + or + $ amcrest-cli --help + + # Saving credentials to file. + $ vim ~/.config/amcrest.conf + [patio] + hostname: 192.168.0.20 + username: admin + password: 123456 + port: 80 + + [living_room] + hostname: 192.168.0.21 + username: admin + password: secret + port: 80 + + $ amcrest-cli --camera living_room --version-http-api + version=1.40 + +Text User Interface (TUI) +------------------------- +Configure amcrest.conf and trigger amcrest-tui, make sure the user +triggering amcrest-tui have access to framebuffer device or use sudo. + +*NOTE:* +Execute it from console logins, like /dev/ttyX (Non X Window). +Pseudo-terminals like xterm, ssh, screen and others WONT WORK. + +.. code-block:: bash + + $ vim ~/.config/amcrest.conf + [patio] + hostname: 192.168.0.20 + username: admin + password: 123456 + port: 80 + + [living_room] + hostname: 192.168.0.21 + username: admin + password: secret + port: 80 + + $ amcrest-tui + + +--------------------- +Supportability Matrix +--------------------- + ++-------------------------+---------------+----------+-----------------+ +| Model | Tested | Status | Results/Issues | ++=========================+===============+==========+=================+ +| IPM-721S | Yes | working | | ++-------------------------+---------------+----------+-----------------+ +| IP2M-841B/841W/842W | Yes | working | | ++-------------------------+---------------+----------+-----------------+ +| IP3M-956E | Yes | working | | ++-------------------------+---------------+----------+-----------------+ +| IPM-HX1B | Yes | working | | ++-------------------------+---------------+----------+-----------------+ + +If you have different model, feel fee to contribute and report your results. + + +---- +Help +---- +If you need any help, please join our community on the Gitter channels available at `Gitter `_. + + + +Developing +========== + +.. autoclass:: amcrest.AmcrestCamera + :members: + :undoc-members: + :show-inheritance: + +.. autoclass:: amcrest.audio.Audio + :members: + :undoc-members: + :show-inheritance: + +.. autoclass:: amcrest.event.Event + :members: + :undoc-members: + :show-inheritance: + +.. autoclass:: amcrest.log.Log + :members: + :undoc-members: + :show-inheritance: + +.. autoclass:: amcrest.motion_detection.MotionDetection + :members: + :undoc-members: + :show-inheritance: + +.. autoclass:: amcrest.nas.Nas + :members: + :undoc-members: + :show-inheritance: + +.. autoclass:: amcrest.network.Network + :members: + :undoc-members: + :show-inheritance: + +.. autoclass:: amcrest.ptz.Ptz + :members: + :undoc-members: + :show-inheritance: + +.. autoclass:: amcrest.record.Record + :members: + :undoc-members: + :show-inheritance: + +.. autoclass:: amcrest.snapshot.Snapshot + :members: + :undoc-members: + :show-inheritance: + +.. autoclass:: amcrest.special.Special + :members: + :undoc-members: + :show-inheritance: + +.. autoclass:: amcrest.storage.Storage + :members: + :undoc-members: + :show-inheritance: + +.. autoclass:: amcrest.system.System + :members: + :undoc-members: + :show-inheritance: + +.. autoclass:: amcrest.user_management.UserManagement + :members: + :undoc-members: + :show-inheritance: + +.. autoclass:: amcrest.video.Video + :members: + :undoc-members: + :show-inheritance: + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..b5fdaea --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,36 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=python -msphinx +) +set SOURCEDIR=. +set BUILDDIR=_build +set SPHINXPROJ=PythonAmcrest + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The Sphinx module was not found. Make sure you have Sphinx installed, + echo.then set the SPHINXBUILD environment variable to point to the full + echo.path of the 'sphinx-build' executable. Alternatively you may add the + echo.Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% + +:end +popd diff --git a/setup.py b/setup.py index 9458b00..b631426 100644 --- a/setup.py +++ b/setup.py @@ -2,7 +2,7 @@ from setuptools import setup, find_packages setup(name='amcrest', - version='1.2.0', + version='1.2.1', description='Python wrapper implementation for Amcrest cameras.', author='Douglas Schilling Landgraf, Marcelo Moreira de Mello', author_email='dougsland@gmail.com, tchello.mello@gmail.com', diff --git a/src/amcrest/http.py b/src/amcrest/http.py index 54dddf2..8d8a7cc 100644 --- a/src/amcrest/http.py +++ b/src/amcrest/http.py @@ -108,6 +108,12 @@ def __repr__(self): """Default object representation.""" return "<{0}: {1}>".format(self._name, self._serial) + def as_dict(self): + """Callback for __dict__.""" + cdict = self.__dict__.copy() + cdict['_token'] = '_redacted' + return cdict + # Base methods def __base_url(self, param=""): return '%s://%s:%s/cgi-bin/%s' % (self._protocol, self._host, diff --git a/tox.ini b/tox.ini index c7b918d..75e2411 100644 --- a/tox.ini +++ b/tox.ini @@ -32,3 +32,4 @@ commands = ignore = D102, E121, +exclude = docs,.tox,*.egg,*.pyc,.git,__pycache