pax_global_header 0000666 0000000 0000000 00000000064 15012115545 0014511 g ustar 00root root 0000000 0000000 52 comment=896894c56a832242e15587f0e990012273636c3a
fritzconnection-1.15.0/ 0000775 0000000 0000000 00000000000 15012115545 0015013 5 ustar 00root root 0000000 0000000 fritzconnection-1.15.0/.coveragerc 0000664 0000000 0000000 00000000225 15012115545 0017133 0 ustar 00root root 0000000 0000000 [report]
exclude_lines =
pragma: no cover
omit =
*/tests/*
*/test_*
*conftest.py
*/cli/*
*fritzhosts.py
*fritzstatus.py
fritzconnection-1.15.0/.gitignore 0000664 0000000 0000000 00000000410 15012115545 0016776 0 ustar 00root root 0000000 0000000
.DS_Store
.coverage
.coveragec
.coveralls.yml
.pytest*
.Python
.tox
.nox
.pytest_cache
.vscode/*
*.ipynb*
*.pyc
__pycache__/*
_jupyter
bin
build/*
dist/*
docs/requirements.out
docs/requirements.local.txt
fritzconnection.egg-info/*
include
lib_
.idea
x_*
docs_out
fritzconnection-1.15.0/.readthedocs.yml 0000664 0000000 0000000 00000000327 15012115545 0020103 0 ustar 00root root 0000000 0000000 version: 2
build:
os: ubuntu-22.04
tools:
python: "3.12"
python:
install:
- requirements: docs/requirements.txt
- method: pip
path: .
sphinx:
builder: html
configuration: docs/conf.py
fritzconnection-1.15.0/CODE_OF_CONDUCT.md 0000664 0000000 0000000 00000001100 15012115545 0017602 0 ustar 00root root 0000000 0000000
# Code of Conduct
## tldr:
There are a lot of CoC files out there and the essence is: be nice and respectful to others and keep in mind that written communication differs from in person communication.
So in comments please don't be negative but neutral, or –even better– all the time friendly. Because every other mode can get misunderstood (and everything misunderstandable will get misunderstood).
However, even then it may happen that one can feel upset in a discussion. In this case take a night of sleep before responding. Also asking questions can help a lot.
fritzconnection-1.15.0/CONTRIBUTING.md 0000664 0000000 0000000 00000010661 15012115545 0017250 0 ustar 00root root 0000000 0000000 # Contributing
Thank you for taking time to contribute to this project.
The project is not large enough to need a lot of rules, but here are some guidelines:
## Issues
In case you think that something is not working as expected or you have a new idea, feel free to create an issue. Especially if you want to provide a pull-request, it is a good idea to create an issue first. Please also keep in mind that issues are not for support. For support try 'discussions' (please keep in mind that this is not a commercial product, so you may get support or not).
## Pull requests
In general pull requests are welcome. Please create an issue first before putting too much work into a pull request that may not get merged at the end, for whatever reason. An issue can help to clarify points of view and motivation.
In case of providing a pull-request please do this for the **development-branch** and not for the master-branch.
For pull-requests there is a golden rule: **keep them small**. Smaller pull-requests are easier to review and easier to merge – especially in cases when not every part of a larger changeset should get merged and has to get modifications.
Please avoid to just change the formatting. The result is most often nothing else than git-diff pollution. This is especially true for `black` (or `blue` or the corresponding modes in `ruff`) – this project startet before `black`. It is ok to use these tools for modified code snippets, but not for a module.
## Status of core and lib
fritzconnection is mainly the code in the core-directory. This code is pretty mature and stable so far.
Most changes are in the library (the lib-directory). The library started mainly as a collection of examples how to use the core. Because it's easier to use an existing function instead of reading the AVM TR-064 documentation, the library modules have grown over time.
But every action supported by AVM can get executed without the library. So best enhancements should not be to trivial.
## Style guide
- In general the style guide is PEP 8.
- Recommended maximum line length is 80 something.
- Use proper names: i.e. an atrribute for `attributes` or `properties`, a verb for `callables`.
- Avoid `black` (see "Pull requests").
## Comments
No new function, method or class should get undocumented. Write meaningful comments: what the code does, about the arguments and return values, and - important - the corresponding types.
## Type hints
This project started long ago without type hints. Keep it that way. The project is small enough, so there is no real benefit. Also some parts of the code are really dynamic (one strength of Python), where type-hints can lead to a nightmare. The place for types in this project are in the comments. Readability counts!
Update: since version `1.13.0` type hints are introduced for the public API (and only there). Type-hints must be backward compatible for the oldest supported python-version. For type-checking `mypy` is used.
## Tests
This project comes with tests. Since version `1.13.0` `nox` is used for testautomation (`https://nox.thea.codes/en/stable/index.html`). `nox` should get installed separately. In the same environment where `nox` has been installed also `ruff` must be installed because the `noxfile` makes use of `ruff` as external module for linting.
After installation the sessions from the `noxfile.py` can be used like:
- `nox -s test`: run the tests with all supported python versions. The supported versions must be installed on the local development system and must be callable like `python3.11` or `python3.12`. Currently python `3.7` and newer are supported (no new language features are used, so backward compatibility is cheap). You can run `nox -s test-3.11` to run the tests with a single python version. This can be handy for development running the test for all versions later on.
- `nox -s test_router`: run all tests making a connection to the router. These tests are taking much more time and can fail because of connection errors. In case of a connection error run the tests again - chances are good the error was temporarly and gone and there are no real bugs. In all other cases: fix it. A test run with a defined python version (here `3.11`) can get started with `nox -s test_router-3.11`.
- `nox -s test_all`: run all tests including the time consuming router-tests.
- `nox -s check`: run `ruff` to `lint` the code.
- `nox -s mypy`: apply a mypy check.
- `nox -s sphinx`: make a local build of the documentation.
fritzconnection-1.15.0/LICENSE.txt 0000664 0000000 0000000 00000002044 15012115545 0016636 0 ustar 00root root 0000000 0000000 Copyright (c) 2012-now Klaus Bremer
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
fritzconnection-1.15.0/MANIFEST.in 0000664 0000000 0000000 00000000204 15012115545 0016545 0 ustar 00root root 0000000 0000000 include README.rst
include LICENSE.txt
include fritzconnection/*.py
include fritzconnection/test_xml/*
include pypi_description.rst
fritzconnection-1.15.0/README.md 0000664 0000000 0000000 00000006046 15012115545 0016300 0 ustar 00root root 0000000 0000000
# fritzconnection


Python-Interface to communicate with the AVM Fritz!Box. Supports the TR-064 protocol, the (AHA-)HTTP-Interface and also allows call-monitoring.
## Installation
For installation use pip:
```
$ pip install fritzconnection
or
$ pip install fritzconnection[qr]
```
The latter will install the [segno](https://github.com/heuer/segno) package to enable QR-code creation for wifi login.
## Quickstart
Using fritzconnection is as easy as:
```
from fritzconnection import FritzConnection
fc = FritzConnection(address="192.168.178.1", user="user", password="pw")
print(fc) # print router model information
# tr-064 interface: reconnect for a new ip
fc.call_action("WANIPConn1", "ForceTermination")
# http interface: gets history data from a device with given 'ain'
fc.call_http("getbasicdevicestats", "12345 7891011")
```
FritzConnection provides two basic commands to communicate with the router APIs: `call_action()` for the __TR-064-Interface__ and `call_http()` for the __(AHA)-HTTP-Interface__. Both APIs can be used on the same FritzConnection instance side by side.
### call_action
`call_action()` expects a __TR-064__ service- and an action-name (and optional arguments). In general FritzConnection can execute every service and action provided by the (model-specific) API as documented by AVM. For i.e. this can be network settings, status informations, access to home automation devices and much more. The `call_action()` method returns the response from the router as a dictionary with the values already converted to the matching Python datatypes.
### call_http
`call_http()` expects a command for the __http-interface__ like "getbasicdevicestats" and, depending on the command, additional arguments like a device "ain" (identifier). A call to the method returns a dictionary with the `content-type`, the `encoding` and the `response` data of the http-response. The content-type of the response-data is typical "text/plain" or "text/xml" and may need further processing.
### Username and password
To avoid hardcoding the arguments `user` and `password` in applications FritzConnection can read both from the environment variables `FRITZ_USERNAME` and `FRITZ_PASSWORD`.
### Caching
On instantiation FritzConnection has to inspect the model-specific router-API. This causes a lot of network requests and can take some seconds. To avoid this FritzConnection provides a cache that can get activated by the `use_cache` parameter:
```
fc = FritzConnection(..., use_cache=True)
```
This argument defaults to `False`. After creating the cache FritzConnection will start up much more faster.
## Library
The package comes with library-modules to make some API calls easier and also demonstrates how to implement applications on top of FritzConnection.
## Documentation
The full documentation and release notes are at [https://fritzconnection.readthedocs.org](https://fritzconnection.readthedocs.org)
fritzconnection-1.15.0/docs/ 0000775 0000000 0000000 00000000000 15012115545 0015743 5 ustar 00root root 0000000 0000000 fritzconnection-1.15.0/docs/_static/ 0000775 0000000 0000000 00000000000 15012115545 0017371 5 ustar 00root root 0000000 0000000 fritzconnection-1.15.0/docs/_static/fritzconnection.css 0000664 0000000 0000000 00000001031 15012115545 0023314 0 ustar 00root root 0000000 0000000
h1 {
font-size: 2.0em;
margin-bottom: 1.5rem;
}
h2 {
border-top: 2px solid #EBEBEB;
border-radius: 0;
margin-top: 3.0rem;
margin-bottom: 1.0rem;
padding-top: 1.5rem;
font-size: 1.5em;
}
h3 {
font-size: 1.2em;
margin-top: 1.75rem;
}
.sidebar-brand-text {
font-size: 1.4em;
}
.theme-toggle-container {
display: none;
}
.toctree-wrapper {
margin-top: 4.0rem;
}
code.docutils span {
color: #941100;
font-weight: 800;
}
section#version-history h2 {
font-size: 1.2em;
}
fritzconnection-1.15.0/docs/conf.py 0000664 0000000 0000000 00000014331 15012115545 0017244 0 ustar 00root root 0000000 0000000 # -*- coding: utf-8 -*-
#
# Configuration file for the Sphinx documentation builder.
#
# This file does only contain a selection of the most common options. For a
# full list see the documentation:
# http://www.sphinx-doc.org/en/master/config
# -- Path setup --------------------------------------------------------------
# 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('..'))
# -- Project information -----------------------------------------------------
# import fritzconnection
import re
from datetime import date
from pathlib import Path
def get_version():
path = Path("..") / "fritzconnection" / "__init__.py"
path = path.resolve() # make it absolute
with open(path) as file:
content = file.read()
mo = re.search(r'\n\s*__version__\s*=\s*[\'"]([^\'"]*)[\'"]', content)
if mo:
return mo.group(1)
raise RuntimeError(f"Unable to find version string in {path}")
project = 'fritzconnection'
copyright = '2013 - {}, Klaus Bremer'.format(date.today().year)
author = 'Klaus Bremer'
# release: the fritzconnection.__version__ as is, including alpha/beta/rc tags
# version: The short X.Y major project version
release = get_version()
version = '.'.join(release.split('.')[:-1])
html_title = f"{project}
{release}"
# -- 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',
]
# 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'
# 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 = 'en'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = ['Thumbs.db', '.DS_Store']
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = "default"
# -- 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 = 'furo'
#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
# documentation.
#
html_theme_options = {
"light_css_variables": {
"admonition-font-size": "0.9375em",
"color-link": "#005493",
"color-link-underline": "#005493",
"color-link--hover": "#941100",
"color-link-underline--hover": "#941100",
"color-sidebar-link-text--top-level": "#941100",
"color-toc-item-text--active": "#941100",
}
}
# 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 = ['_static']
# Custom sidebar templates, must be a dictionary that maps document names
# to template names.
#
# The default sidebars (for documents that don't match any pattern) are
# defined by theme itself. Builtin themes are using these templates by
# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
# 'searchbox.html']``.
#
# html_sidebars = {}
html_css_files = ['fritzconnection.css']
html_show_sphinx = True
# -- Options for HTMLHelp output ---------------------------------------------
# Output file base name for HTML help builder.
htmlhelp_basename = 'fritzconnectiondoc'
# -- 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, 'fritzconnection.tex', 'fritzconnection Documentation',
'Klaus Bremer', '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, 'fritzconnection', 'fritzconnection 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, 'fritzconnection', 'fritzconnection Documentation',
author, 'fritzconnection', 'One line description of project.',
'Miscellaneous'),
]
# -- Options for Epub output -------------------------------------------------
# Bibliographic Dublin Core info.
epub_title = project
# The unique identifier of the text. This can be a ISBN number
# or the project homepage.
#
# epub_identifier = ''
# A unique identification for the text.
#
# epub_uid = ''
# A list of files that should not be packed into the epub file.
epub_exclude_files = ['search.html']
# -- Extension configuration -------------------------------------------------
fritzconnection-1.15.0/docs/fritzconnection-360x76.png 0000664 0000000 0000000 00000025160 15012115545 0022546 0 ustar 00root root 0000000 0000000 PNG
IHDR h L @-A *7IDATx]ytUսݛf% )jg>B]P{oo2eʔ)|fA E
)A+(((R(VPPPP0HZAAAaB "hA
E
)A+(((R(VPP(B:HDzljj*r~b(N 6~NAAA2#v'G!!!fi[p8>,
݄K``u"hˉa;dLr_pRss;vLJKKq
6*%%e+~ia^сx"hˁ|e Քn+py~vJZZ:TRSS}YYYn8' 2yZAA?1䖖 P$g_ ΗSNɉ'4]UUuSSn8
b@Yk!{N:$V?e"ރcTk((
0"mmm<'ptsgۃL"K}}FǏNOusx-=NKfFqavö|A6X$l2`#-9Y;;!W>yw2PvO)(0\'.4cBCC8$t$c={V#i*lZMMFⸯvExH;55UA''EA P߷ANvW6ð/{Izlߥt`Cc)++ۅaXr~~ć:S
l3´ɿ\&wm$lZrcc