Merge pull request #19 from adafruit/black-update

Black reformatting with Python 3 target.

.github/workflows/build.yml

@@ -0,0 +1,57 @@
+name: Build CI
+
+on: [pull_request, push]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+    - name: Dump GitHub context
+      env:
+        GITHUB_CONTEXT: ${{ toJson(github) }}
+      run: echo "$GITHUB_CONTEXT"
+    - name: Translate Repo Name For Build Tools filename_prefix
+      id: repo-name
+      run: |
+        echo ::set-output name=repo-name::$(
+        echo ${{ github.repository }} |
+        awk -F '\/' '{ print tolower($2) }' |
+        tr '_' '-'
+        )
+    - name: Set up Python 3.6
+      uses: actions/setup-python@v1
+      with:
+        python-version: 3.6
+    - name: Versions
+      run: |
+        python3 --version
+    - name: Checkout Current Repo
+      uses: actions/checkout@v1
+      with:
+        submodules: true
+    - name: Checkout tools repo
+      uses: actions/checkout@v2
+      with:
+        repository: adafruit/actions-ci-circuitpython-libs
+        path: actions-ci
+    - name: Install dependencies
+      # (e.g. - apt-get: gettext, etc; pip: circuitpython-build-tools, requirements.txt; etc.)
+      run: |
+        source actions-ci/install.sh
+    - name: Pip install pylint, black, & Sphinx
+      run: |
+        pip install --force-reinstall pylint black==19.10b0 Sphinx sphinx-rtd-theme
+    - name: Library version
+      run: git describe --dirty --always --tags
+    - name: Check formatting
+      run: |
+        black --check --target-version=py35 .
+    - name: PyLint
+      run: |
+        pylint $( find . -path './adafruit*.py' )
+        ([[ ! -d "examples" ]] || pylint --disable=missing-docstring,invalid-name,bad-whitespace $( find . -path "./examples/*.py" ))
+    - name: Build assets
+      run: circuitpython-build-bundles --filename_prefix ${{ steps.repo-name.outputs.repo-name }} --library_location .
+    - name: Build docs
+      working-directory: docs
+      run: sphinx-build -E -W -b html . _build/html

.github/workflows/release.yml

@@ -0,0 +1,81 @@
+name: Release Actions
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  upload-release-assets:
+    runs-on: ubuntu-latest
+    steps:
+    - name: Dump GitHub context
+      env:
+        GITHUB_CONTEXT: ${{ toJson(github) }}
+      run: echo "$GITHUB_CONTEXT"
+    - name: Translate Repo Name For Build Tools filename_prefix
+      id: repo-name
+      run: |
+        echo ::set-output name=repo-name::$(
+        echo ${{ github.repository }} |
+        awk -F '\/' '{ print tolower($2) }' |
+        tr '_' '-'
+        )
+    - name: Set up Python 3.6
+      uses: actions/setup-python@v1
+      with:
+        python-version: 3.6
+    - name: Versions
+      run: |
+        python3 --version
+    - name: Checkout Current Repo
+      uses: actions/checkout@v1
+      with:
+        submodules: true
+    - name: Checkout tools repo
+      uses: actions/checkout@v2
+      with:
+        repository: adafruit/actions-ci-circuitpython-libs
+        path: actions-ci
+    - name: Install deps
+      run: |
+        source actions-ci/install.sh
+    - name: Build assets
+      run: circuitpython-build-bundles --filename_prefix ${{ steps.repo-name.outputs.repo-name }} --library_location .
+    - name: Upload Release Assets
+      # the 'official' actions version does not yet support dynamically
+      # supplying asset names to upload. @csexton's version chosen based on
+      # discussion in the issue below, as its the simplest to implement and
+      # allows for selecting files with a pattern.
+      # https://github.com/actions/upload-release-asset/issues/4
+      #uses: actions/upload-release-asset@v1.0.1
+      uses: csexton/release-asset-action@master
+      with:
+        pattern: "bundles/*"
+        github-token: ${{ secrets.GITHUB_TOKEN }}
+
+  upload-pypi:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v1
+    - name: Check For setup.py
+      id: need-pypi
+      run: |
+        echo ::set-output name=setup-py::$( find . -wholename './setup.py' )
+    - name: Set up Python
+      if: contains(steps.need-pypi.outputs.setup-py, 'setup.py')
+      uses: actions/setup-python@v1
+      with:
+        python-version: '3.x'
+    - name: Install dependencies
+      if: contains(steps.need-pypi.outputs.setup-py, 'setup.py')
+      run: |
+        python -m pip install --upgrade pip
+        pip install setuptools wheel twine
+    - name: Build and publish
+      if: contains(steps.need-pypi.outputs.setup-py, 'setup.py')
+      env:
+        TWINE_USERNAME: ${{ secrets.pypi_username }}
+        TWINE_PASSWORD: ${{ secrets.pypi_password }}
+      run: |
+        python setup.py sdist
+        twine upload dist/*

.gitignore

@@ -4,7 +4,6 @@ __pycache__
 _build
 *.pyc
 .env
-build*
 bundles
 *.DS_Store
 .eggs

.pylintrc

@@ -52,7 +52,7 @@ confidence=
 # no Warning level messages displayed, use"--disable=all --enable=classes
 # --disable=W"
 # disable=import-error,print-statement,parameter-unpacking,unpacking-in-except,old-raise-syntax,backtick,long-suffix,old-ne-operator,old-octal-literal,import-star-module-level,raw-checker-failed,bad-inline-option,locally-disabled,locally-enabled,file-ignored,suppressed-message,useless-suppression,deprecated-pragma,apply-builtin,basestring-builtin,buffer-builtin,cmp-builtin,coerce-builtin,execfile-builtin,file-builtin,long-builtin,raw_input-builtin,reduce-builtin,standarderror-builtin,unicode-builtin,xrange-builtin,coerce-method,delslice-method,getslice-method,setslice-method,no-absolute-import,old-division,dict-iter-method,dict-view-method,next-method-called,metaclass-assignment,indexing-exception,raising-string,reload-builtin,oct-method,hex-method,nonzero-method,cmp-method,input-builtin,round-builtin,intern-builtin,unichr-builtin,map-builtin-not-iterating,zip-builtin-not-iterating,range-builtin-not-iterating,filter-builtin-not-iterating,using-cmp-argument,eq-without-hash,div-method,idiv-method,rdiv-method,exception-message-attribute,invalid-str-codec,sys-max-int,bad-python3-import,deprecated-string-function,deprecated-str-translate-call
-disable=print-statement,parameter-unpacking,unpacking-in-except,old-raise-syntax,backtick,long-suffix,old-ne-operator,old-octal-literal,import-star-module-level,raw-checker-failed,bad-inline-option,locally-disabled,locally-enabled,file-ignored,suppressed-message,useless-suppression,deprecated-pragma,apply-builtin,basestring-builtin,buffer-builtin,cmp-builtin,coerce-builtin,execfile-builtin,file-builtin,long-builtin,raw_input-builtin,reduce-builtin,standarderror-builtin,unicode-builtin,xrange-builtin,coerce-method,delslice-method,getslice-method,setslice-method,no-absolute-import,old-division,dict-iter-method,dict-view-method,next-method-called,metaclass-assignment,indexing-exception,raising-string,reload-builtin,oct-method,hex-method,nonzero-method,cmp-method,input-builtin,round-builtin,intern-builtin,unichr-builtin,map-builtin-not-iterating,zip-builtin-not-iterating,range-builtin-not-iterating,filter-builtin-not-iterating,using-cmp-argument,eq-without-hash,div-method,idiv-method,rdiv-method,exception-message-attribute,invalid-str-codec,sys-max-int,bad-python3-import,deprecated-string-function,deprecated-str-translate-call,import-error
+disable=print-statement,parameter-unpacking,unpacking-in-except,old-raise-syntax,backtick,long-suffix,old-ne-operator,old-octal-literal,import-star-module-level,raw-checker-failed,bad-inline-option,locally-disabled,locally-enabled,file-ignored,suppressed-message,useless-suppression,deprecated-pragma,apply-builtin,basestring-builtin,buffer-builtin,cmp-builtin,coerce-builtin,execfile-builtin,file-builtin,long-builtin,raw_input-builtin,reduce-builtin,standarderror-builtin,unicode-builtin,xrange-builtin,coerce-method,delslice-method,getslice-method,setslice-method,no-absolute-import,old-division,dict-iter-method,dict-view-method,next-method-called,metaclass-assignment,indexing-exception,raising-string,reload-builtin,oct-method,hex-method,nonzero-method,cmp-method,input-builtin,round-builtin,intern-builtin,unichr-builtin,map-builtin-not-iterating,zip-builtin-not-iterating,range-builtin-not-iterating,filter-builtin-not-iterating,using-cmp-argument,eq-without-hash,div-method,idiv-method,rdiv-method,exception-message-attribute,invalid-str-codec,sys-max-int,bad-python3-import,deprecated-string-function,deprecated-str-translate-call,import-error,bad-continuation
 
 # Enable the message, report, category or checker with the given id(s). You can
 # either give multiple identifier separated by comma (,) or put this option
@@ -119,7 +119,8 @@ spelling-store-unknown-words=no
 [MISCELLANEOUS]
 
 # List of note tags to take in consideration, separated by a comma.
-notes=FIXME,XXX,TODO
+# notes=FIXME,XXX,TODO
+notes=FIXME,XXX
 
 
 [TYPECHECK]

.travis.yml

@@ -1,32 +0,0 @@
-dist: trusty
-sudo: false
-language: python
-python:
-- '3.6'
-cache:
-  pip: true
-deploy:
-- provider: releases
-  api_key: "$GITHUB_TOKEN"
-  file_glob: true
-  file: "$TRAVIS_BUILD_DIR/bundles/*"
-  skip_cleanup: true
-  overwrite: true
-  on:
-    tags: true
-- provider: pypi
-  user: adafruit-travis
-  on:
-    tags: true
-  password:
-    secure: v9T3N0ak+VL+DdAVurMPcDS+GIXSt8DFNCfXZwC7SUK5Yen5pWeeY4Ul+qt5KUUrgzawQQwrPt7wj1YPWQvusvVN1FNGTrua9JCnGFY113ij+MeniZOiAC2prROhaa1n+Cjm8eOSgCWFiNYxR30YrcDI4LovHVrrcocdcMfo5w0GXryIRMIKTGSVD5mISCPV/QXqv5lNkY0wpNZ8edjj8xVrPtZvVldWNSNsezkyFlzdHNtXLm3SuL7Zk8uCWuEVooKQosofe8uBKiOF4WZXFh+45bBZ5UzaGtUsK/Gm2Xdmy2KfWbmJXyTUkI4Zc74fmGASmV3e2L5taI813HOizl8kjTV3BvO7NuvutSqgeZy4Jod7H/yrfp6lIjP9PdyY6typnLg5j1pXElz52xqk3oUkTGG6FuEeMIION4H6zxptOPD8wxVvhHQW9C5iICI/Zwas7fP8ksVzR3IiwmynogilzmEGaW1p4oMycfSZ/ZKALmHfWh4370GD5JB4d9dO+HRdGuJzOZj0g2/zus3RMWzet4uQDtiLw7P9PJ9vHpjBOo5OWvqOYk4Ll08IZ0aMe+qdPUg8/JQ2/zd5Jus6quI3CfT/gZfZuVZ/ATG8hZFx9xNAW6JTQw5Ca+2DC8ghuQve2ohf8bYd25wW5JV5bpOuLiZRC/m/EOa+yBLJNko=
-install:
-- pip install -r requirements.txt
-- pip install pylint circuitpython-build-tools Sphinx sphinx-rtd-theme
-- pip install --force-reinstall pylint==1.9.2
-script:
-- pylint adafruit_ds18x20.py
-- ([[ ! -d "examples" ]] || pylint --disable=missing-docstring,invalid-name examples/*.py)
-- circuitpython-build-bundles --filename_prefix adafruit-circuitpython-ds18x20 --library_location
-  .
-- cd docs && sphinx-build -E -W -b html . _build/html && cd ..

CODE_OF_CONDUCT.md

@@ -34,13 +34,15 @@ Examples of unacceptable behavior by participants include:
 * Excessive or unwelcome helping; answering outside the scope of the question
   asked
 * Trolling, insulting/derogatory comments, and personal or political attacks
+* Promoting or spreading disinformation, lies, or conspiracy theories against
+  a person, group, organisation, project, or community
 * Public or private harassment
 * Publishing others' private information, such as a physical or electronic
   address, without explicit permission
 * Other conduct which could reasonably be considered inappropriate
 
 The goal of the standards and moderation guidelines outlined here is to build
-and maintain a respectful community. We ask that you don’t just aim to be
+and maintain a respectful community. We ask that you don’t just aim to be
 "technically unimpeachable", but rather try to be your best self. 
 
 We value many things beyond technical expertise, including collaboration and
@@ -72,10 +74,10 @@ You may report in the following ways:
 In any situation, you may send an email to <support@adafruit.com>.
 
 On the Adafruit Discord, you may send an open message from any channel
-to all Community Helpers by tagging @community helpers. You may also send an
-open message from any channel, or a direct message to @kattni#1507,
-@tannewt#4653, @Dan Halbert#1614, @cater#2442, @sommersoft#0222, or
-@Andon#8175.
+to all Community Moderators by tagging @community moderators. You may 
+also send an open message from any channel, or a direct message to 
+@kattni#1507, @tannewt#4653, @Dan Halbert#1614, @cater#2442, 
+@sommersoft#0222, @Mr. Certainly#0472 or @Andon#8175.
 
 Email and direct message reports will be kept confidential.
 
@@ -83,7 +85,7 @@ In situations on Discord where the issue is particularly egregious, possibly
 illegal, requires immediate action, or violates the Discord terms of service,
 you should also report the message directly to Discord.
 
-These are the steps for upholding our community’s standards of conduct.
+These are the steps for upholding our community’s standards of conduct.
 
 1. Any member of the community may report any situation that violates the
 Adafruit Community Code of Conduct. All reports will be reviewed and
@@ -124,4 +126,4 @@ For other projects adopting the Adafruit Community Code of
 Conduct, please contact the maintainers of those projects for enforcement.
 If you wish to use this code of conduct for your own project, consider
 explicitly mentioning your moderation policy or making a copy with your
-own moderation policy so as to avoid confusion.
+own moderation policy so as to avoid confusion.

README.rst

@@ -10,8 +10,8 @@ Introduction
     :target: https://adafru.it/discord
     :alt: Discord
 
-.. image:: https://travis-ci.org/adafruit/Adafruit_CircuitPython_DS18X20.svg?branch=master
-    :target: https://travis-ci.org/adafruit/Adafruit_CircuitPython_DS18X20
+.. image:: https://github.com/adafruit/Adafruit_CircuitPython_DS18X20/workflows/Build%20CI/badge.svg
+    :target: https://github.com/adafruit/Adafruit_CircuitPython_DS18X20/actions/
     :alt: Build Status
 
 CircuitPython driver for Dallas 1-Wire temperature sensor.
@@ -27,6 +27,31 @@ Please ensure all dependencies are available on the CircuitPython filesystem.
 This is easily achieved by downloading
 `the Adafruit library and driver bundle <https://github.com/adafruit/Adafruit_CircuitPython_Bundle>`_.
 
+Installing from PyPI
+====================
+
+On supported GNU/Linux systems like the Raspberry Pi, you can install the driver locally `from
+PyPI <https://pypi.org/project/adafruit-circuitpython-ds18x20/>`_. To install for current user:
+
+.. code-block:: shell
+
+    pip3 install adafruit-circuitpython-ds18x20
+
+To install system-wide (this may be required in some cases):
+
+.. code-block:: shell
+
+    sudo pip3 install adafruit-circuitpython-ds18x20
+
+To install in a virtual environment in your current project:
+
+.. code-block:: shell
+
+    mkdir project-name && cd project-name
+    python3 -m venv .env
+    source .env/bin/activate
+    pip3 install adafruit-circuitpython-ds18x20
+
 Usage Example
 =============
 
@@ -47,49 +72,7 @@ Contributions are welcome! Please read our `Code of Conduct
 <https://github.com/adafruit/Adafruit_CircuitPython_DS18X20/blob/master/CODE_OF_CONDUCT.md>`_
 before contributing to help this project stay welcoming.
 
-Building locally
-================
+Documentation
+=============
 
-To build this library locally you'll need to install the
-`circuitpython-build-tools <https://github.com/adafruit/circuitpython-build-tools>`_ package.
-
-.. code-block:: shell
-
-    python3 -m venv .env
-    source .env/bin/activate
-    pip install circuitpython-build-tools
-
-Once installed, make sure you are in the virtual environment:
-
-.. code-block:: shell
-
-    source .env/bin/activate
-
-Then run the build:
-
-.. code-block:: shell
-
-    circuitpython-build-bundles --filename_prefix adafruit-circuitpython-ds18x20 --library_location .
-
-Sphinx documentation
------------------------
-
-Sphinx is used to build the documentation based on rST files and comments in the code. First,
-install dependencies (feel free to reuse the virtual environment from above):
-
-.. code-block:: shell
-
-    python3 -m venv .env
-    source .env/bin/activate
-    pip install Sphinx sphinx-rtd-theme
-
-Now, once you have the virtual environment activated:
-
-.. code-block:: shell
-
-    cd docs
-    sphinx-build -E -W -b html . _build/html
-
-This will output the documentation to ``docs/_build/html``. Open the index.html in your browser to
-view them. It will also (due to -W) error out on any warning like Travis will. This is a good way to
-locally verify it will pass.
+For information on building library documentation, please check out `this guide <https://learn.adafruit.com/creating-and-sharing-a-circuitpython-library/sharing-our-docs-on-readthedocs#sphinx-5-1>`_.

adafruit_ds18x20.py

@@ -32,16 +32,19 @@ __version__ = "0.0.0-auto.0"
 __repo__ = "https://github.com/adafruit/Adafruit_CircuitPython_DS18x20.git"
 
 import time
-from adafruit_onewire.device import OneWireDevice
 from micropython import const
+from adafruit_onewire.device import OneWireDevice
 
-_CONVERT = b'\x44'
-_RD_SCRATCH = b'\xBE'
-_WR_SCRATCH = b'\x4E'
+_CONVERT = b"\x44"
+_RD_SCRATCH = b"\xBE"
+_WR_SCRATCH = b"\x4E"
 _CONVERSION_TIMEOUT = const(1)
 RESOLUTION = (9, 10, 11, 12)
+# Maximum conversion delay in seconds, from DS18B20 datasheet.
+_CONVERSION_DELAY = {9: 0.09375, 10: 0.1875, 11: 0.375, 12: 0.750}
 
-class DS18X20(object):
+
+class DS18X20:
     """Class which provides interface to DS18X20 temperature sensor."""
 
     def __init__(self, bus, address):
@@ -49,8 +52,9 @@ class DS18X20(object):
             self._address = address
             self._device = OneWireDevice(bus, address)
             self._buf = bytearray(9)
+            self._conv_delay = _CONVERSION_DELAY[12]  # pessimistic default
         else:
-            raise ValueError('Incorrect family code in device address.')
+            raise ValueError("Incorrect family code in device address.")
 
     @property
     def temperature(self):
@@ -66,10 +70,10 @@ class DS18X20(object):
     @resolution.setter
     def resolution(self, bits):
         if bits not in RESOLUTION:
-            raise ValueError('Incorrect resolution. Must be 9, 10, 11, or 12.')
+            raise ValueError("Incorrect resolution. Must be 9, 10, 11, or 12.")
         self._buf[0] = 0  # TH register
         self._buf[1] = 0  # TL register
-        self._buf[2] = RESOLUTION.index(bits) << 5 | 0x1F # configuration register
+        self._buf[2] = RESOLUTION.index(bits) << 5 | 0x1F  # configuration register
         self._write_scratch(self._buf)
 
     def _convert_temp(self, timeout=_CONVERSION_TIMEOUT):
@@ -81,7 +85,9 @@ class DS18X20(object):
                 # 0 = conversion in progress, 1 = conversion done
                 while self._buf[0] == 0x00:
                     if time.monotonic() - start_time > timeout:
-                        raise RuntimeError('Timeout waiting for conversion to complete.')
+                        raise RuntimeError(
+                            "Timeout waiting for conversion to complete."
+                        )
                     dev.readinto(self._buf, end=1)
         return time.monotonic() - start_time
 
@@ -91,15 +97,14 @@ class DS18X20(object):
         if self._address.family_code == 0x10:
             if buf[1]:
                 t = buf[0] >> 1 | 0x80
-                t = -((~t + 1) & 0xff)
+                t = -((~t + 1) & 0xFF)
             else:
                 t = buf[0] >> 1
             return t - 0.25 + (buf[7] - buf[6]) / buf[7]
-        else:
-            t = buf[1] << 8 | buf[0]
-            if t & 0x8000: # sign bit set
-                t = -((t ^ 0xffff) + 1)
-            return t / 16
+        t = buf[1] << 8 | buf[0]
+        if t & 0x8000:  # sign bit set
+            t = -((t ^ 0xFFFF) + 1)
+        return t / 16
 
     def _read_scratch(self):
         with self._device as dev:
@@ -111,3 +116,15 @@ class DS18X20(object):
         with self._device as dev:
             dev.write(_WR_SCRATCH)
             dev.write(buf, end=3)
+
+    def start_temperature_read(self):
+        """Start asynchronous conversion, returns immediately.
+        Returns maximum conversion delay [seconds] based on resolution."""
+        with self._device as dev:
+            dev.write(_CONVERT)
+        return _CONVERSION_DELAY[self.resolution]
+
+    def read_temperature(self):
+        """Read the temperature. No polling of the conversion busy bit
+        (assumes that the conversion has completed)."""
+        return self._read_temp()

docs/conf.py

@@ -2,7 +2,8 @@
 
 import os
 import sys
-sys.path.insert(0, os.path.abspath('..'))
+
+sys.path.insert(0, os.path.abspath(".."))
 
 # -- General configuration ------------------------------------------------
 
@@ -10,9 +11,9 @@ sys.path.insert(0, os.path.abspath('..'))
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'sphinx.ext.autodoc',
-    'sphinx.ext.intersphinx',
-    'sphinx.ext.viewcode',
+    "sphinx.ext.autodoc",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.viewcode",
 ]
 
 # Uncomment the below if you use native CircuitPython modules such as
@@ -20,29 +21,32 @@ extensions = [
 # autodoc module docs will fail to generate with a warning.
 # autodoc_mock_imports = ["adafruit_onewire", "micropython", "time"]
 
-intersphinx_mapping = {'python': ('https://docs.python.org/3.4', None),'CircuitPython': ('https://circuitpython.readthedocs.io/en/latest/', None)}
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3.4", None),
+    "CircuitPython": ("https://circuitpython.readthedocs.io/en/latest/", None),
+}
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+templates_path = ["_templates"]
 
-source_suffix = '.rst'
+source_suffix = ".rst"
 
 # The master toctree document.
-master_doc = 'index'
+master_doc = "index"
 
 # General information about the project.
-project = u'Adafruit DS18X20 Library'
-copyright = u'2017 Carter Nelson'
-author = u'Carter Nelson'
+project = "Adafruit DS18X20 Library"
+copyright = "2017 Carter Nelson"
+author = "Carter Nelson"
 
 # 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 = u'1.0'
+version = "1.0"
 # The full version, including alpha/beta/rc tags.
-release = u'1.0'
+release = "1.0"
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -54,7 +58,7 @@ 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', '.env', 'CODE_OF_CONDUCT.md']
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", ".env", "CODE_OF_CONDUCT.md"]
 
 # The reST default role (used for this markup: `text`) to use for all
 # documents.
@@ -66,7 +70,7 @@ default_role = "any"
 add_function_parentheses = True
 
 # The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
+pygments_style = "sphinx"
 
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = False
@@ -80,59 +84,62 @@ todo_emit_warnings = True
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
+on_rtd = os.environ.get("READTHEDOCS", None) == "True"
 
 if not on_rtd:  # only import and set the theme if we're building docs locally
     try:
         import sphinx_rtd_theme
-        html_theme = 'sphinx_rtd_theme'
-        html_theme_path = [sphinx_rtd_theme.get_html_theme_path(), '.']
+
+        html_theme = "sphinx_rtd_theme"
+        html_theme_path = [sphinx_rtd_theme.get_html_theme_path(), "."]
     except:
-        html_theme = 'default'
-        html_theme_path = ['.']
+        html_theme = "default"
+        html_theme_path = ["."]
 else:
-    html_theme_path = ['.']
+    html_theme_path = ["."]
 
 # 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']
+html_static_path = ["_static"]
 
 # The name of an image file (relative to this directory) to use as a favicon of
 # the docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
 # pixels large.
 #
-html_favicon = '_static/favicon.ico'
+html_favicon = "_static/favicon.ico"
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'AdafruitDs18x20Librarydoc'
+htmlhelp_basename = "AdafruitDs18x20Librarydoc"
 
 # -- 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',
+    # 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, 'AdafruitDS18X20Library.tex', u'AdafruitDS18X20 Library Documentation',
-     author, 'manual'),
+    (
+        master_doc,
+        "AdafruitDS18X20Library.tex",
+        "AdafruitDS18X20 Library Documentation",
+        author,
+        "manual",
+    ),
 ]
 
 # -- Options for manual page output ---------------------------------------
@@ -140,8 +147,13 @@ latex_documents = [
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    (master_doc, 'AdafruitDS18X20library', u'Adafruit DS18X20 Library Documentation',
-     [author], 1)
+    (
+        master_doc,
+        "AdafruitDS18X20library",
+        "Adafruit DS18X20 Library Documentation",
+        [author],
+        1,
+    )
 ]
 
 # -- Options for Texinfo output -------------------------------------------
@@ -150,7 +162,13 @@ man_pages = [
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-    (master_doc, 'AdafruitDS18X20Library', u'Adafruit DS18X20 Library Documentation',
-     author, 'AdafruitDS18X20Library', 'One line description of project.',
-     'Miscellaneous'),
+    (
+        master_doc,
+        "AdafruitDS18X20Library",
+        "Adafruit DS18X20 Library Documentation",
+        author,
+        "AdafruitDS18X20Library",
+        "One line description of project.",
+        "Miscellaneous",
+    ),
 ]

docs/examples.rst

@@ -1,8 +1,12 @@
 Simple test
 ------------
 
-Ensure your device works with this simple test.
+Ensure your device works with these simple tests.
 
 .. literalinclude:: ../examples/ds18x20_simpletest.py
     :caption: examples/ds18x20_simpletest.py
     :linenos:
+
+.. literalinclude:: ../examples/ds18x20_asynctest.py
+    :caption: examples/ds18x20_asynctest.py
+    :linenos:

examples/ds18x20_asynctest.py

@@ -0,0 +1,31 @@
+# Simple demo of printing the temperature from the first found DS18x20 sensor every second.
+# Using the asynchronous functions start_temperature_read() and
+# read_temperature() to allow the main loop to keep processing while
+# the conversion is in progress.
+# Author: Louis Bertrand, based on original by Tony DiCola
+
+# A 4.7Kohm pullup between DATA and POWER is REQUIRED!
+
+import time
+import board
+from adafruit_onewire.bus import OneWireBus
+from adafruit_ds18x20 import DS18X20
+
+
+# Initialize one-wire bus on board pin D1.
+ow_bus = OneWireBus(board.D1)
+
+# Scan for sensors and grab the first one found.
+ds18 = DS18X20(ow_bus, ow_bus.scan()[0])
+ds18.resolution = 12
+
+# Main loop to print the temperature every second.
+while True:
+    conversion_delay = ds18.start_temperature_read()
+    conversion_ready_at = time.monotonic() + conversion_delay
+    print("waiting", end="")
+    while time.monotonic() < conversion_ready_at:
+        print(".", end="")
+        time.sleep(0.1)
+    print("\nTemperature: {0:0.3f}C\n".format(ds18.read_temperature()))
+    time.sleep(1.0)

examples/ds18x20_simpletest.py

@@ -1,9 +1,10 @@
 # Simple demo of printing the temperature from the first found DS18x20 sensor every second.
 # Author: Tony DiCola
+
+# A 4.7Kohm pullup between DATA and POWER is REQUIRED!
+
 import time
-
 import board
-
 from adafruit_onewire.bus import OneWireBus
 from adafruit_ds18x20 import DS18X20
 
@@ -16,5 +17,5 @@ ds18 = DS18X20(ow_bus, ow_bus.scan()[0])
 
 # Main loop to print the temperature every second.
 while True:
-    print('Temperature: {0:0.3f}C'.format(ds18.temperature))
+    print("Temperature: {0:0.3f}C".format(ds18.temperature))
     time.sleep(1.0)

setup.py

@@ -7,6 +7,7 @@ https://github.com/pypa/sampleproject
 
 # Always prefer setuptools over distutils
 from setuptools import setup, find_packages
+
 # To use a consistent encoding
 from codecs import open
 from os import path
@@ -14,48 +15,39 @@ from os import path
 here = path.abspath(path.dirname(__file__))
 
 # Get the long description from the README file
-with open(path.join(here, 'README.rst'), encoding='utf-8') as f:
+with open(path.join(here, "README.rst"), encoding="utf-8") as f:
     long_description = f.read()
 
 setup(
-    name='adafruit-circuitpython-ds18x20',
-
+    name="adafruit-circuitpython-ds18x20",
     use_scm_version=True,
-    setup_requires=['setuptools_scm'],
-
-    description='CircuitPython driver for Dallas 1-Wire temperature sensor.',
+    setup_requires=["setuptools_scm"],
+    description="CircuitPython driver for Dallas 1-Wire temperature sensor.",
     long_description=long_description,
-    long_description_content_type='text/x-rst',
-
+    long_description_content_type="text/x-rst",
     # The project's main homepage.
-    url='https://github.com/adafruit/Adafruit_CircuitPython_DS18X20',
-
+    url="https://github.com/adafruit/Adafruit_CircuitPython_DS18X20",
     # Author details
-    author='Adafruit Industries',
-    author_email='circuitpython@adafruit.com',
-
-    install_requires=['Adafruit-Blinka', 'adafruit-circuitpython-onewire'],
-
+    author="Adafruit Industries",
+    author_email="circuitpython@adafruit.com",
+    install_requires=["Adafruit-Blinka", "adafruit-circuitpython-onewire"],
     # Choose your license
-    license='MIT',
-
+    license="MIT",
     # See https://pypi.python.org/pypi?%3Aaction=list_classifiers
     classifiers=[
-        'Development Status :: 3 - Alpha',
-        'Intended Audience :: Developers',
-        'Topic :: Software Development :: Libraries',
-        'Topic :: System :: Hardware',
-        'License :: OSI Approved :: MIT License',
-        'Programming Language :: Python :: 3',
-        'Programming Language :: Python :: 3.4',
-        'Programming Language :: Python :: 3.5',
+        "Development Status :: 3 - Alpha",
+        "Intended Audience :: Developers",
+        "Topic :: Software Development :: Libraries",
+        "Topic :: System :: Hardware",
+        "License :: OSI Approved :: MIT License",
+        "Programming Language :: Python :: 3",
+        "Programming Language :: Python :: 3.4",
+        "Programming Language :: Python :: 3.5",
     ],
-
     # What does your project relate to?
-    keywords='adafruit 1-wire temperature sensor ds18x20 '
-             'hardware breakout micropython circuitpython',
-
+    keywords="adafruit 1-wire temperature sensor ds18x20 "
+    "hardware breakout micropython circuitpython",
     # You can just specify the packages manually here if your project is
     # simple. Or you can use find_packages().
-    py_modules=['adafruit_ds18x20'],
+    py_modules=["adafruit_ds18x20"],
 )