Skip to content

Commit

Permalink
Update sections of the documentation mentioning Python 2.7
Browse files Browse the repository at this point in the history
Closes #337.

These sections now explain why the library has retained support for
Python 2.7 after the EOL deadline for that version.
  • Loading branch information
drmfinlay committed Mar 22, 2022
1 parent c1db9e1 commit aace875
Show file tree
Hide file tree
Showing 2 changed files with 30 additions and 21 deletions.
39 changes: 23 additions & 16 deletions documentation/faq.txt
Original file line number Diff line number Diff line change
Expand Up @@ -106,22 +106,30 @@ the two versions.
How can I use older Dragonfly scripts with Dragonfly2?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Older dragonfly scripts are mostly written with Python 2.x in mind. Python
version 2.7 has reached the end of its life as of January 2020 (see
`Python 2.7 EOL`_). For complicated reasons, Dragonfly's Python 3.x support
has come a bit later than most other active projects. You will need to
convert older Python 2.x code, to use it with Python 3.x. There are a few
ways to convert older code:

* `2to3`_ - command-line program that reads Python 2.x source code and
applies a series of fixers to transform it into valid Python 3.x code.
* `python-modernize`_ - a command-line program that uses *2to3* to make
Python 2 code compatible with Python 3.
This version of Dragonfly has been written with backwards-compatibility in
mind. Older Dragonfly scripts, many of which were written with Python
version 2 in mind, will either work perfectly without any changes or will
after minor changes.

Although Python version 2.7 reached the end of its life in January 2020,
Dragonfly has, for the most part, retained support for it. This has been
done because the library has always supported Python 2 and because retaining
this support is, at present, neither difficult nor detrimental to the
library's support for Python version 3. The Kaldi engine back-end is the
one (optional) component of Dragonfly that requires Python version 3.

To use older Python 2 code with Python 3, it first needs to be converted.
The following two command-line programs may be used to this end:

* `2to3`_ - reads Python 2 source code and applies a series of fixers to
transform it into valid Python 3 code.
* `python-modernize`_ - uses *2to3* to make Python 2 code compatible with
Python 3.

You may be interested in the `Python 2-3 code porting guide`_ if you prefer
to do things manually.

A number of older dragonfly command modules also include the following code:
A number of older Dragonfly command modules also include the following code:

.. code-block:: python

Expand Down Expand Up @@ -365,9 +373,9 @@ error messages not mentioned in the FAQ, then see the
How do I fix "No handlers could be found for logger X" error messages?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This error is specific to Python 2.x. It isn't a Dragonfly error, but as
many users still use Python 2.7, it is listed here. This is the most common
example of the error: ::
This error is specific to Python 2. It isn't a Dragonfly error, but as many
Dragonfly users still use Python 2, it is listed here. This is the most
common example of the error: ::

No handlers could be found for logger "action"

Expand Down Expand Up @@ -659,7 +667,6 @@ touch:
.. _Matrix channel: https://app.element.io/#/room/#dictation-toolbox_dragonfly:gitter.im
.. _Natlink Troubleshooting page: https://qh.antenna.nl/unimacro/installation/installforpython27/problemswithinstallation.html
.. _Python 2-3 code porting guide: https://docs.python.org/3/howto/pyporting.html
.. _Python 2.7 EOL: https://www.python.org/dev/peps/pep-0373/
.. _Security Considerations for Assistive Technologies: https://docs.microsoft.com/en-us/windows/win32/winauto/uiauto-securityoverview
.. _Setting the default DPI awareness for a process: https://docs.microsoft.com/en-us/windows/win32/hidpi/setting-the-default-dpi-awareness-for-a-process
.. _User Account Control: https://en.wikipedia.org/wiki/User_Account_Control
Expand Down
12 changes: 7 additions & 5 deletions documentation/installation.txt
Original file line number Diff line number Diff line change
Expand Up @@ -30,11 +30,13 @@ To be able to use the dragonfly, you will need the following:
for Linux/X11 users)* -- usually available from your system's package
manager.

**Note on Python 2.7**: Python version 2.7 (32-bit) is required if using the
Natlink engine back-end, at least for the moment. Support for this version
is not maintained for the other engine back-ends and will be **dropped
completely** in the first *MAJOR* release following stable Natlink support
for Python 3.
**Note on Python 2**: Python version 2.7 (32-bit) is required if using the
Natlink SR engine, at least for the moment. With the exception of the Kaldi
engine, Python 2 support has been retained for the whole library. Other
than the fact that this support is currently required for the Natlink
engine, this has been done because the library has always supported this
version of Python and because retaining said support is, at present, neither
difficult nor detrimental to the library's support for Python version 3.

**Note for Linux users**: Dragonfly is only fully functional in an X11
session. You may also need to manually set the ``DISPLAY`` environment
Expand Down

0 comments on commit aace875

Please sign in to comment.