Merge rst-toplevel-8054: Change the top level documents to be Restructured Text, and make them otherwise nicer
Author: hawkowl Reviewer: adiroiban Fixes: #8054 git-svn-id: svn://svn.twistedmatrix.com/svn/Twisted/trunk@46217 bbbe8e31-12d6-0310-92fd-ac37d47ddeeb
This commit is contained in:
parent
88589e181b
commit
dded0aee91
40
INSTALL
40
INSTALL
|
@ -1,40 +0,0 @@
|
|||
Requirements
|
||||
|
||||
Python 2.7 (full functionality) or 3.3/3.4/3.5 (subset of functionality).
|
||||
|
||||
setuptools <https://pypi.python.org/pypi/setuptools>.
|
||||
|
||||
Zope Interface 3.6.0 or newer (<https://pypi.python.org/pypi/zope.interface>).
|
||||
Zope Interface 4.0 or newer is required for Python 3.
|
||||
|
||||
pyOpenSSL (<https://github.com/pyca/pyopenssl>) is required for any SSL APIs.
|
||||
Version 0.13 or newer is required, but 0.15.1 or newer is recommended.
|
||||
|
||||
On Windows pywin32 (<https://pypi.python.org/pypi/pypiwin32>) is required.
|
||||
Build 215 or later is highly recommended for reliable operation
|
||||
(this is already included in ActivePython).
|
||||
|
||||
If you would like to use Trial's subunit reporter, then you will need to
|
||||
install Subunit 0.0.2 or later (<https://launchpad.net/subunit>).
|
||||
|
||||
Installation
|
||||
|
||||
* Debian and Ubuntu
|
||||
Packages are included in the main distribution.
|
||||
|
||||
* FreeBSD, Gentoo
|
||||
Twisted is in their package repositories.
|
||||
|
||||
* Win32
|
||||
Installers are available from <https://twistedmatrix.com/>.
|
||||
|
||||
* pip
|
||||
The latest released version of Twisted can be installed by pip:
|
||||
|
||||
pip install Twisted
|
||||
|
||||
* Other
|
||||
As with other Python packages, the standard way of installing from source
|
||||
is:
|
||||
|
||||
python setup.py install
|
|
@ -0,0 +1,42 @@
|
|||
Installing Twisted
|
||||
==================
|
||||
|
||||
Installation Requirements
|
||||
-------------------------
|
||||
|
||||
To install Twisted, you need:
|
||||
|
||||
- Python 2.7 (full functionality) or 3.3/3.4/3.5 (subset of functionality).
|
||||
|
||||
- `setuptools <https://pypi.python.org/pypi/setuptools>`_
|
||||
(installed automatically if you use pip).
|
||||
|
||||
- `Zope Interface <https://pypi.python.org/pypi/zope.interface>`_ 3.6.0 or newer.
|
||||
Zope Interface 4.0 or newer is required for Python 3.
|
||||
Installing via pip will automatically download a suitable Zope Interface.
|
||||
|
||||
- On Windows `pywin32 <https://pypi.python.org/pypi/pypiwin32>`_ is required.
|
||||
Build 219 or later is highly recommended for reliable operation (this is already included in ActivePython).
|
||||
|
||||
We also have `setuptools extras <http://twistedmatrix.com/documents/current/installation/howto/optional.html>`_ for automatically installing optional packages used by Twisted.
|
||||
|
||||
|
||||
Installing Twisted
|
||||
------------------
|
||||
|
||||
To install the latest version of Twisted using pip::
|
||||
|
||||
$ pip install twisted
|
||||
|
||||
You can install optional dependencies for specific functionality in Twisted (such as TLS or serial support) by using our setuptools extras (see above).
|
||||
|
||||
As an example, to install Twisted with the TLS dependencies, use::
|
||||
|
||||
$ pip install twisted[tls]
|
||||
|
||||
Additionally, there are packages available in the repositories of:
|
||||
|
||||
- Debian and Ubuntu as ``python-twisted`` for Python 2.
|
||||
- FreeBSD as ``py-twisted`` for Python 2.
|
||||
- Arch as ``python-twisted`` for Python 2.
|
||||
- Fedora and RHEL as ``python-twisted`` for Python 2.
|
114
README
114
README
|
@ -1,114 +0,0 @@
|
|||
Twisted 15.4.0
|
||||
|
||||
Release Codename:
|
||||
|
||||
"Trial By Fire"
|
||||
|
||||
|
||||
For information on what's new in Twisted 15.4.0, see the NEWS file that comes
|
||||
with the distribution.
|
||||
|
||||
What is this?
|
||||
=============
|
||||
|
||||
Twisted is an event-based framework for internet applications. It includes
|
||||
modules for many different purposes, including the following:
|
||||
|
||||
- twisted.application
|
||||
A "Service" system that allows you to organize your application in
|
||||
hierarchies with well-defined startup and dependency semantics,
|
||||
- twisted.cred
|
||||
A general credentials and authentication system that facilitates
|
||||
pluggable authentication backends,
|
||||
- twisted.enterprise
|
||||
Asynchronous database access, compatible with any Python DBAPI2.0
|
||||
modules,
|
||||
- twisted.internet
|
||||
Low-level asynchronous networking APIs that allow you to define
|
||||
your own protocols that run over certain transports,
|
||||
- twisted.manhole
|
||||
A tool for remote debugging of your services which gives you a
|
||||
Python interactive interpreter,
|
||||
- twisted.protocols
|
||||
Basic protocol implementations and helpers for your own protocol
|
||||
implementations,
|
||||
- twisted.python
|
||||
A large set of utilities for Python tricks, reflection, text
|
||||
processing, and anything else,
|
||||
- twisted.spread
|
||||
A secure, fast remote object system,
|
||||
- twisted.trial
|
||||
A unit testing framework that integrates well with Twisted-based code.
|
||||
|
||||
Twisted supports integration of the Win32, Tk, GTK+ and GTK+ 2 event loops
|
||||
with its main event loop. There is experimental support for Mac OS X and
|
||||
wxPython event loop integration, which you use at your peril.
|
||||
|
||||
For more information, visit http://www.twistedmatrix.com, or join the list
|
||||
at http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python
|
||||
|
||||
There are many official Twisted subprojects, including clients and
|
||||
servers for web, mail, DNS, and more. You can find out more about
|
||||
these projects at http://twistedmatrix.com/trac/wiki/TwistedProjects
|
||||
|
||||
|
||||
Installing
|
||||
==========
|
||||
|
||||
Instructions for installing this software are in INSTALL.
|
||||
|
||||
Unit Tests
|
||||
==========
|
||||
|
||||
See our unit tests run proving that the software is BugFree(TM):
|
||||
|
||||
% trial twisted
|
||||
|
||||
Some of these tests may fail if you
|
||||
* don't have the dependancies required for a particular subsystem installed,
|
||||
* have a firewall blocking some ports (or things like Multicast, which Linux
|
||||
NAT has shown itself to do), or
|
||||
* run them as root.
|
||||
|
||||
|
||||
Documentation and Support
|
||||
=========================
|
||||
|
||||
Twisted's documentation is available from the Twisted Matrix website:
|
||||
|
||||
http://twistedmatrix.com/documents/current/
|
||||
|
||||
This documentation contains how-tos, code examples, and an API reference.
|
||||
|
||||
Help is also available on the Twisted mailing list:
|
||||
|
||||
http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python
|
||||
|
||||
There is also a pair of very lively IRC channels, #twisted (for general
|
||||
Twisted questions) and #twisted.web (for Twisted Web), on chat.freenode.net.
|
||||
|
||||
|
||||
Copyright
|
||||
=========
|
||||
|
||||
All of the code in this distribution is Copyright (c) 2001-2015
|
||||
Twisted Matrix Laboratories.
|
||||
|
||||
Twisted is made available under the MIT license. The included
|
||||
LICENSE file describes this in detail.
|
||||
|
||||
|
||||
Warranty
|
||||
========
|
||||
|
||||
THIS SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER
|
||||
EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
|
||||
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
|
||||
TO THE USE OF THIS SOFTWARE IS WITH YOU.
|
||||
|
||||
IN NO EVENT WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY
|
||||
AND/OR REDISTRIBUTE THE LIBRARY, BE LIABLE TO YOU FOR ANY DAMAGES, EVEN IF
|
||||
SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
|
||||
DAMAGES.
|
||||
|
||||
Again, see the included LICENSE file for specific legal details.
|
|
@ -0,0 +1,98 @@
|
|||
Twisted 15.4.0
|
||||
==============
|
||||
|
||||
|pypi|_
|
||||
|coverage|_
|
||||
|
||||
Release Codename:
|
||||
|
||||
"Trial By Fire"
|
||||
|
||||
For information on what's new in Twisted 15.4.0, see the `NEWS <NEWS>`_ file that comes with the distribution.
|
||||
|
||||
|
||||
What is this?
|
||||
-------------
|
||||
|
||||
Twisted is an event-based framework for internet applications, supporting Python 2.7 and Python 3.3+.
|
||||
It includes modules for many different purposes, including the following:
|
||||
|
||||
- ``twisted.web``: HTTP clients and servers, HTML templating, and a WSGI server
|
||||
- ``twisted.conch``: SSHv2 and Telnet clients and servers and terminal emulators
|
||||
- ``twisted.words``: Clients and servers for IRC, XMPP, and other IM protocols
|
||||
- ``twisted.mail``: IMAPv4, POP3, SMTP clients and servers
|
||||
- ``twisted.positioning``: Tools for communicating with NMEA-compatible GPS recievers
|
||||
- ``twisted.names``: DNS client and tools for making your own DNS servers
|
||||
- ``twisted.trial``: A unit testing framework that integrates well with Twisted-based code.
|
||||
|
||||
Twisted supports all major system event loops -- ``select`` (all platforms), ``poll`` (most POSIX platforms), ``epoll`` (Linux), ``kqueue`` (FreeBSD, OS X), IOCP (Windows), and various GUI event loops (GTK+2/3, QT, wxWidgets).
|
||||
Third-party reactors can plug into Twisted, and provide support for additional event loops.
|
||||
|
||||
|
||||
Installing
|
||||
----------
|
||||
|
||||
To install the latest version of Twisted using pip::
|
||||
|
||||
$ pip install twisted
|
||||
|
||||
Additional instructions for installing this software are in `the installation instructions <INSTALL.rst>`_.
|
||||
|
||||
|
||||
Documentation and Support
|
||||
-------------------------
|
||||
|
||||
Twisted's documentation is available from the `Twisted Matrix website <http://twistedmatrix.com/documents/current/>`_.
|
||||
This documentation contains how-tos, code examples, and an API reference.
|
||||
|
||||
Help is also available on the `Twisted mailing list <http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python>`_.
|
||||
|
||||
There is also a pair of very lively IRC channels, ``#twisted`` (for general Twisted questions) and ``#twisted.web`` (for Twisted Web), on ``chat.freenode.net``.
|
||||
|
||||
|
||||
Unit Tests
|
||||
----------
|
||||
|
||||
Twisted has a comprehensive test suite, which can be run by ``tox``::
|
||||
|
||||
$ tox -l # to view all test environments
|
||||
$ tox -e py27-tests # to run the tests for Python 2.7
|
||||
$ tox -e py34-tests # to run the tests for Python 3.4
|
||||
|
||||
Some of these tests may fail if you:
|
||||
|
||||
* don't have the dependencies required for a particular subsystem installed,
|
||||
* have a firewall blocking some ports (or things like Multicast, which Linux NAT has shown itself to do), or
|
||||
* run them as root.
|
||||
|
||||
|
||||
Copyright
|
||||
---------
|
||||
|
||||
All of the code in this distribution is Copyright (c) 2001-2015 Twisted Matrix Laboratories.
|
||||
|
||||
Twisted is made available under the MIT license.
|
||||
The included `LICENSE <LICENSE>`_ file describes this in detail.
|
||||
|
||||
|
||||
Warranty
|
||||
--------
|
||||
|
||||
THIS SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER
|
||||
EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
|
||||
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
|
||||
TO THE USE OF THIS SOFTWARE IS WITH YOU.
|
||||
|
||||
IN NO EVENT WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY
|
||||
AND/OR REDISTRIBUTE THE LIBRARY, BE LIABLE TO YOU FOR ANY DAMAGES, EVEN IF
|
||||
SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
|
||||
DAMAGES.
|
||||
|
||||
Again, see the included `LICENSE <LICENSE>`_ file for specific legal details.
|
||||
|
||||
|
||||
.. |coverage| image:: https://codecov.io/github/twisted/twisted/coverage.svg?branch=trunk
|
||||
.. _coverage: https://codecov.io/github/twisted/twisted
|
||||
|
||||
.. |pypi| image:: http://img.shields.io/pypi/v/twisted.svg
|
||||
.. _pypi: https://pypi.python.org/pypi/twisted
|
|
@ -389,7 +389,7 @@ def changeAllProjectVersions(root, prerelease, patch, today=None):
|
|||
|
||||
# Then change the global version.
|
||||
twistedProject.updateVersion(newVersion)
|
||||
_changeVersionInFile(oldVersion, newVersion, root.child('README').path)
|
||||
_changeVersionInFile(oldVersion, newVersion, root.child('README.rst').path)
|
||||
|
||||
|
||||
|
||||
|
|
|
@ -353,7 +353,7 @@ class ChangeVersionTests(ExternalTempdirTestCase, StructureAssertingMixin):
|
|||
"""
|
||||
root = FilePath(self.mktemp())
|
||||
structure = {
|
||||
"README": "Hi this is 1.0.0.",
|
||||
"README.rst": "Hi this is 1.0.0.",
|
||||
"twisted": {
|
||||
"topfiles": {
|
||||
"README": "Hi this is 1.0.0"},
|
||||
|
@ -364,7 +364,7 @@ class ChangeVersionTests(ExternalTempdirTestCase, StructureAssertingMixin):
|
|||
releaseDate = date(2010, 1, 1)
|
||||
changeAllProjectVersions(root, False, False, releaseDate)
|
||||
outStructure = {
|
||||
"README": "Hi this is 10.0.0.",
|
||||
"README.rst": "Hi this is 10.0.0.",
|
||||
"twisted": {
|
||||
"topfiles": {
|
||||
"README": "Hi this is 10.0.0"},
|
||||
|
@ -389,7 +389,7 @@ class ChangeVersionTests(ExternalTempdirTestCase, StructureAssertingMixin):
|
|||
"==================================\n"
|
||||
"\n")
|
||||
structure = {
|
||||
"README": "Hi this is 1.0.0pre1.",
|
||||
"README.rst": "Hi this is 1.0.0pre1.",
|
||||
"NEWS": coreNews + webNews,
|
||||
"twisted": {
|
||||
"topfiles": {
|
||||
|
@ -411,7 +411,7 @@ class ChangeVersionTests(ExternalTempdirTestCase, StructureAssertingMixin):
|
|||
"==============================\n"
|
||||
"\n")
|
||||
outStructure = {
|
||||
"README": "Hi this is 1.0.0.",
|
||||
"README.rst": "Hi this is 1.0.0.",
|
||||
"NEWS": coreNews + webNews,
|
||||
"twisted": {
|
||||
"topfiles": {
|
||||
|
@ -1542,7 +1542,7 @@ class DistributionBuilderTests(DistributionBuilderTestBase):
|
|||
"""
|
||||
manInput1 = "pretend there's some troff in here or something"
|
||||
structure = {
|
||||
"README": "Twisted",
|
||||
"README.rst": "Twisted",
|
||||
"unrelated": "x",
|
||||
"LICENSE": "copyright!",
|
||||
"setup.py": "import toplevel",
|
||||
|
@ -1572,7 +1572,7 @@ class DistributionBuilderTests(DistributionBuilderTestBase):
|
|||
return True
|
||||
|
||||
outStructure = {
|
||||
"README": "Twisted",
|
||||
"README.rst": "Twisted",
|
||||
"unrelated": "x",
|
||||
"LICENSE": "copyright!",
|
||||
"setup.py": "import toplevel",
|
||||
|
@ -1666,7 +1666,7 @@ class BuildAllTarballsTestBase(object):
|
|||
self._init(checkout)
|
||||
|
||||
structure = {
|
||||
"README": "Twisted",
|
||||
"README.rst": "Twisted",
|
||||
"unrelated": "x",
|
||||
"LICENSE": "copyright!",
|
||||
"setup.py": "import toplevel",
|
||||
|
@ -1696,7 +1696,7 @@ class BuildAllTarballsTestBase(object):
|
|||
return True
|
||||
|
||||
twistedStructure = {
|
||||
"README": "Twisted",
|
||||
"README.rst": "Twisted",
|
||||
"unrelated": "x",
|
||||
"LICENSE": "copyright!",
|
||||
"setup.py": "import toplevel",
|
||||
|
@ -2025,7 +2025,7 @@ class CommandsTestMixin(StructureAssertingMixin):
|
|||
repository as identical in a specified directory.
|
||||
"""
|
||||
structure = {
|
||||
"README": "Hi this is 1.0.0.",
|
||||
"README.rst": "Hi this is 1.0.0.",
|
||||
"twisted": {
|
||||
"topfiles": {
|
||||
"README": "Hi this is 1.0.0"},
|
||||
|
|
Loading…
Reference in New Issue