diff options
Diffstat (limited to 'docs/faq.rst')
| -rw-r--r-- | docs/faq.rst | 90 |
1 files changed, 52 insertions, 38 deletions
diff --git a/docs/faq.rst b/docs/faq.rst index 6d876610f..d6f4ad336 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -1,6 +1,33 @@ Frequently asked questions ========================== +.. _faq-howto-handle-deprecation-warning: + +I cannot suppress the deprecation warning that ``cryptography`` emits on import +------------------------------------------------------------------------------- + +.. hint:: + + The deprecation warning emitted on import does not inherit + :py:exc:`DeprecationWarning` but inherits :py:exc:`UserWarning` + instead. + +If your pytest setup follows the best practices of failing on +emitted warnings (``filterwarnings = error``), you may ignore it +by adding the following line at the end of the list:: + + ignore:Python 2 is no longer supported by the Python core team. Support for it is now deprecated in cryptography, and will be removed in a future release.:UserWarning + +**Note:** Using ``cryptography.utils.CryptographyDeprecationWarning`` +is not possible here because specifying it triggers +``import cryptography`` internally that emits the warning before +the ignore rule even kicks in. + +Ref: https://github.com/pytest-dev/pytest/issues/7524 + +The same applies when you use :py:func:`~warnings.filterwarnings` in +your code or invoke CPython with :std:option:`-W` command line option. + ``cryptography`` failed to install! ----------------------------------- @@ -43,18 +70,17 @@ legacy libraries: :class:`AES-GCM <cryptography.hazmat.primitives.ciphers.modes.GCM>` and :class:`~cryptography.hazmat.primitives.kdf.hkdf.HKDF`. -Compiling ``cryptography`` on macOS produces a ``fatal error: 'openssl/aes.h' file not found`` error ----------------------------------------------------------------------------------------------------- +Installing ``cryptography`` produces a ``fatal error: 'openssl/opensslv.h' file not found`` error +------------------------------------------------------------------------------------------------- -This happens because macOS 10.11 no longer includes a copy of OpenSSL. -``cryptography`` now provides wheels which include a statically linked copy of -OpenSSL. You're seeing this error because your copy of pip is too old to find -our wheel files. Upgrade your copy of pip with ``pip install -U pip`` and then -try install ``cryptography`` again. +``cryptography`` provides wheels which include a statically linked copy of +OpenSSL. If you see this error it is likely because your copy of ``pip`` is too +old to find our wheel files. Upgrade your ``pip`` with ``pip install -U pip`` +and then try to install ``cryptography`` again. -If you are using PyPy, we do not currently ship ``cryptography`` wheels for -PyPy. You will need to install your own copy of OpenSSL -- we recommend using -Homebrew. +Users on PyPy, unusual CPU architectures, or distributions of Linux using +``musl`` (like Alpine) will need to compile ``cryptography`` themselves. Please +view our :doc:`/installation` documentation. ``cryptography`` raised an ``InternalError`` and I'm not sure what to do? ------------------------------------------------------------------------- @@ -82,34 +108,22 @@ Your ``pip`` and/or ``setuptools`` are outdated. Please upgrade to the latest versions with ``pip install -U pip setuptools`` (or on Windows ``python -m pip install -U pip setuptools``). -Installing cryptography with OpenSSL 0.9.8 or 1.0.0 fails ---------------------------------------------------------- - -The OpenSSL project has dropped support for the 0.9.8 and 1.0.0 release series. -Since they are no longer receiving security patches from upstream, -``cryptography`` is also dropping support for them. To fix this issue you -should upgrade to a newer version of OpenSSL (1.0.2 or later). This may require -you to upgrade to a newer operating system. - -Why are there no wheels for Python 3.5+ on Linux or macOS? ----------------------------------------------------------- - -Our Python3 wheels, for macOS and Linux, are ``abi3`` wheels. This means they -support multiple versions of Python. The Python 3.4 ``abi3`` wheel can be used -with any version of Python greater than or equal to 3.4. Recent versions of -``pip`` will automatically install ``abi3`` wheels. - -``ImportError``: ``idna`` is not installed ------------------------------------------- - -``cryptography`` deprecated passing :term:`U-label` strings to various X.509 -constructors in version 2.1 and in version 2.5 moved the ``idna`` dependency -to a ``setuptools`` extra. If you see this exception you should upgrade your -software so that it no longer depends on this deprecated feature. If that is -not yet possible you can also install ``cryptography`` with -``pip install cryptography[idna]`` to automatically install the missing -dependency. This workaround will be available until the feature is fully -removed. +Installing cryptography with OpenSSL 0.9.8, 1.0.0, 1.0.1, 1.0.2 fails +--------------------------------------------------------------------- + +The OpenSSL project has dropped support for the 0.9.8, 1.0.0, 1.0.1, and 1.0.2 +release series. Since they are no longer receiving security patches from +upstream, ``cryptography`` is also dropping support for them. To fix this issue +you should upgrade to a newer version of OpenSSL (1.1.0 or later). This may +require you to upgrade to a newer operating system. + +Why are there no wheels for my Python3.x version? +------------------------------------------------- + +Our Python3 wheels are ``abi3`` wheels. This means they support multiple +versions of Python. The ``abi3`` wheel can be used with any version of Python +greater than or equal to the version it specifies. Recent versions of ``pip`` +will automatically install ``abi3`` wheels. Why can't I import my PEM file? ------------------------------- |