From 70820fc7c0fd0189c246c9c1e519b15c8dc0fe1c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sa=C3=BAl=20Ibarra=20Corretg=C3=A9?= Date: Mon, 18 Oct 2021 12:25:53 +0200 Subject: [PATCH] misc: add PyPI README without images --- PYPIREADME.rst | 125 +++++++++++++++++++++++++++++++++++++++++++++++++ setup.py | 2 +- 2 files changed, 126 insertions(+), 1 deletion(-) create mode 100644 PYPIREADME.rst diff --git a/PYPIREADME.rst b/PYPIREADME.rst new file mode 100644 index 0000000..76e4f4b --- /dev/null +++ b/PYPIREADME.rst @@ -0,0 +1,125 @@ +Looking for new maintainers +=========================== + +https://github.com/saghul/pycares/issues/139 + +pycares: Python interface for c-ares +==================================== + +pycares is a Python module which provides an interface to c-ares. +`c-ares `_ is a C library that performs +DNS requests and name resolutions asynchronously. + + +Documentation +------------- + +http://readthedocs.org/docs/pycares/ + + +Bundled c-ares +-------------- + +pycares currently bundles c-ares as a submodule for ease of building. Using the system +provided c-ares is possible if the ``PYCARES_USE_SYSTEM_LIB`` environment variable is +set to ``1`` when building. + +NOTE: Versions prior to 4.0.0 used to embed a modified c-ares with extended TTL support. +That is no longer the case and as a result only A and AAAA records will have TTL information. +Follow this PR in uppstream c-ares, looks like TTLs will be added: https://github.com/c-ares/c-ares/pull/393 + + +Installation +------------ + +GNU/Linux, macOS, Windows, others: + +:: + + pip install pycares + +FreeBSD: + +:: + + cd /usr/ports/dns/py-pycares && make install + + +IDNA 2008 support +^^^^^^^^^^^^^^^^^ + +If the ``idna`` package is installed, pycares will support IDNA 2008 encoding otherwise the builtin idna codec will be used, +which provides IDNA 2003 support. + +You can force this at installation time as follows: + +:: + + pip install pycares[idna] + + +Running the test suite +---------------------- + +There are several ways of running the test suite: + +- Run the test with the current Python interpreter: + + From the toplevel directory, run: ``python tests/tests.py`` + +- Use Tox to run the test suite in several virtualenvs with several interpreters + + From the toplevel directory, run: ``tox -e py36,py37,py38,py39`` this will run the test suite + on Python 3.6 through 3.9 (you'll need to have them installed beforehand) + + +Using it from the cli, a la dig +------------------------------- + +This module can be used directly from the command line in a similar fashion to dig (limited, of course): + +:: + + $ python -m pycares google.com + ;; QUESTION SECTION: + ;google.com IN A + + ;; ANSWER SECTION: + google.com 300 IN A 172.217.17.142 + + $ python -m pycares mx google.com + ;; QUESTION SECTION: + ;google.com IN MX + + ;; ANSWER SECTION: + google.com 600 IN MX 50 alt4.aspmx.l.google.com + google.com 600 IN MX 10 aspmx.l.google.com + google.com 600 IN MX 40 alt3.aspmx.l.google.com + google.com 600 IN MX 20 alt1.aspmx.l.google.com + google.com 600 IN MX 30 alt2.aspmx.l.google.com + + +Author +------ + +Saúl Ibarra Corretgé + + +License +------- + +Unless stated otherwise on-file pycares uses the MIT license, check LICENSE file. + + +Supported Python versions +------------------------- + +Python >= 3.6 are supported. Both CPython and PyPy are supported. + + +Contributing +------------ + +If you'd like to contribute, fork the project, make a patch and send a pull +request. Have a look at the surrounding code and please, make yours look +alike :-) diff --git a/setup.py b/setup.py index 2122504..2b7a505 100755 --- a/setup.py +++ b/setup.py @@ -20,7 +20,7 @@ def get_version(): license = 'MIT', url = 'http://github.com/saghul/pycares', description = 'Python interface for c-ares', - long_description = codecs.open('README.rst', encoding='utf-8').read(), + long_description = codecs.open('PYPIREADME.rst', encoding='utf-8').read(), long_description_content_type = 'text/x-rst', platforms = ['POSIX', 'Microsoft Windows'], classifiers = [