mirror of
https://github.com/kennethreitz/dive-into-python3.git
synced 2026-06-05 23:10:17 +00:00
added chardet examples to #divingin and #structure, finished #setuppy section
This commit is contained in:
Mark Pilgrim
+93
-72
@@ -5,7 +5,7 @@
|
||||
<!--[if IE]><script src=j/html5.js></script><![endif]-->
|
||||
<link rel=stylesheet href=dip3.css>
|
||||
<style>
|
||||
body{counter-reset:h1 16}
|
||||
body{counter-reset:h1 17}
|
||||
</style>
|
||||
<link rel=stylesheet media='only screen and (max-device-width: 480px)' href=mobile.css>
|
||||
<link rel=stylesheet media=print href=print.css>
|
||||
@@ -24,81 +24,56 @@ body{counter-reset:h1 16}
|
||||
|
||||
<p>Python 3 comes with a packaging framework called Distutils. Distutils is many things: a build tool (for you), an installation tool (for your users), a package metadata format (for search engines), and more. It integrates with the <a href=http://pypi.python.org/>Python Package Index</a> (“PyPI”), a central repository for open source Python libraries.
|
||||
|
||||
<p>All of these facets of Distutils center around the <i>setup script</i>, traditionally called <code>setup.py</code>. In fact, you’ve already seen a Distutils setup script: <a href=http-web-services.html#introducing-httplib2>you used one to install <code>httplib2</code></a> in the “HTTP Web Services” chapter.
|
||||
<p>All of these facets of Distutils center around the <i>setup script</i>, traditionally called <code>setup.py</code>. In fact, you’ve already seen several Distutils setup scripts in this book: <a href=http-web-services.html#introducing-httplib2>you used one to install <code>httplib2</code></a> in “HTTP Web Services,” and <a href=case-study-porting-chardet-to-python-3.html>another to install <code>chardet</code></a> in “Case Study: Porting <code>chardet</code> to Python 3.”
|
||||
|
||||
<p>In this chapter, you’ll learn how the setup script for <a href=http://code.google.com/p/httplib2/><code>httplib2</code></a> works and step through the process of releasing your own Python software.
|
||||
<p>In this chapter, you’ll learn how the setup script for <code>chardet</code> works and step through the process of releasing your own Python software.
|
||||
|
||||
<pre><code class=pp># httplib2's setup.py
|
||||
<pre><code class=pp># chardet's setup.py
|
||||
from distutils.core import setup
|
||||
VERSION = '0.5.0'
|
||||
setup(name='httplib2',
|
||||
version=VERSION,
|
||||
author='Joe Gregorio',
|
||||
author_email='joe@example.com',
|
||||
url='http://code.google.com/p/httplib2/',
|
||||
download_url='http://httplib2.googlecode.com/files/httplib2-python3-{}.tar.gz'.format(VERSION),
|
||||
description='A comprehensive HTTP client library.',
|
||||
license='MIT',
|
||||
packages=['httplib2'],
|
||||
classifiers=[
|
||||
'Development Status :: 4 - Beta',
|
||||
'Environment :: Web Environment',
|
||||
'Intended Audience :: Developers',
|
||||
'License :: OSI Approved :: MIT License',
|
||||
'Operating System :: OS Independent',
|
||||
'Programming Language :: Python',
|
||||
'Programming Language :: Python :: 3',
|
||||
'Topic :: Internet :: WWW/HTTP',
|
||||
'Topic :: Software Development :: Libraries :: Python Modules',
|
||||
],
|
||||
long_description="""
|
||||
setup(
|
||||
name = "chardet",
|
||||
packages = ["chardet"],
|
||||
version = "1.0.1",
|
||||
description = "Universal encoding detector",
|
||||
author = "Mark Pilgrim",
|
||||
author_email = "mark@diveintomark.org",
|
||||
url = "http://chardet.feedparser.org/",
|
||||
download_url = "http://chardet.feedparser.org/download/python3-chardet-1.0.1.tgz",
|
||||
keywords = ["encoding", "i18n", "xml"],
|
||||
classifiers = [
|
||||
"Programming Language :: Python",
|
||||
"Programming Language :: Python :: 3",
|
||||
"Development Status :: 4 - Beta",
|
||||
"Environment :: Other Environment",
|
||||
"Intended Audience :: Developers",
|
||||
"License :: OSI Approved :: GNU Library or Lesser General Public License (LGPL)",
|
||||
"Operating System :: OS Independent",
|
||||
"Topic :: Software Development :: Libraries :: Python Modules",
|
||||
"Topic :: Text Processing :: Linguistic",
|
||||
],
|
||||
long_description = """\
|
||||
Universal character encoding detector
|
||||
-------------------------------------
|
||||
|
||||
A comprehensive HTTP client library, ``httplib2`` supports many features left out of other HTTP libraries.
|
||||
Detects
|
||||
- ASCII, UTF-8, UTF-16 (2 variants), UTF-32 (4 variants)
|
||||
- Big5, GB2312, EUC-TW, HZ-GB-2312, ISO-2022-CN (Traditional and Simplified Chinese)
|
||||
- EUC-JP, SHIFT_JIS, ISO-2022-JP (Japanese)
|
||||
- EUC-KR, ISO-2022-KR (Korean)
|
||||
- KOI8-R, MacCyrillic, IBM855, IBM866, ISO-8859-5, windows-1251 (Cyrillic)
|
||||
- ISO-8859-2, windows-1250 (Hungarian)
|
||||
- ISO-8859-5, windows-1251 (Bulgarian)
|
||||
- windows-1252 (English)
|
||||
- ISO-8859-7, windows-1253 (Greek)
|
||||
- ISO-8859-8, windows-1255 (Visual and Logical Hebrew)
|
||||
- TIS-620 (Thai)
|
||||
|
||||
**HTTP and HTTPS**
|
||||
HTTPS support is only available if the socket module was compiled with SSL support.
|
||||
|
||||
|
||||
**Keep-Alive**
|
||||
Supports HTTP 1.1 Keep-Alive, keeping the socket open and performing multiple requests over the same connection if possible.
|
||||
|
||||
|
||||
**Authentication**
|
||||
The following three types of HTTP Authentication are supported. These can be used over both HTTP and HTTPS.
|
||||
|
||||
* Digest
|
||||
* Basic
|
||||
* WSSE
|
||||
|
||||
**Caching**
|
||||
The module can optionally operate with a private cache that understands the Cache-Control:
|
||||
header and uses both the ETag and Last-Modified cache validators. Both file system
|
||||
and memcached based caches are supported.
|
||||
|
||||
|
||||
**All Methods**
|
||||
The module can handle any HTTP request method, not just GET and POST.
|
||||
|
||||
|
||||
**Redirects**
|
||||
Automatically follows 3XX redirects on GETs.
|
||||
|
||||
|
||||
**Compression**
|
||||
Handles both 'deflate' and 'gzip' types of compression.
|
||||
|
||||
|
||||
**Lost update support**
|
||||
Automatically adds back ETags into PUT requests to resources we have already cached. This implements Section 3.2 of Detecting the Lost Update Problem Using Unreserved Checkout
|
||||
|
||||
|
||||
**Unit Tested**
|
||||
A large and growing set of unit tests.
|
||||
"""
|
||||
This version requires Python 3 or later; a Python 2 version is available separately.
|
||||
"""
|
||||
)</code></pre>
|
||||
|
||||
<blockquote class=note>
|
||||
<p><span class=u>☞</span><code>httplib2</code> is open source, but there’s no requirement that you release your own Python libraries under any particular license. The process described in this chapter will work for any Python software, regardless of license.
|
||||
<p><span class=u>☞</span><code>chardet</code> and <code>httplib2</code> are open source, but there’s no requirement that you release your own Python libraries under any particular license. The process described in this chapter will work for any Python software, regardless of license.
|
||||
</blockquote>
|
||||
|
||||
<p class=a>⁂
|
||||
@@ -143,7 +118,31 @@ A comprehensive HTTP client library, ``httplib2`` supports many features left ou
|
||||
<li>If your Python software is a single <code>.py</code> file, you should put it in the root directory along with your “read me” file and your setup script. If it’s a multi-file module (<i>i.e.</i> a directory with a main <code>__init__.py</code> script), like <code>httplib2</code>, you should put the entire directory here. Yes, that means you’ll have an <code>httplib2/</code> directory within an <code>httplib2/</code> directory. Trust me, that’s not a problem. In fact, any other arrangement would be a problem.
|
||||
</ol>
|
||||
|
||||
<p>Depending on the license you chose, you may include the license text within your <code>.py</code> files themselves, or you may have a separate file containing license text, or both. <abbr>GPL</abbr>-licensed programs generally include a file called <code>COPYING</code> that includes the entire text of the <abbr>GPL</abbr>. If you have a separate license file, it should go in the root directory along with your “read me” file and your setup script.
|
||||
<p>The <code>chardet</code> directory looks slightly different. Instead of a “read me” file, it has <abbr>HTML</abbr>-formatted documentation in a <code>docs/</code> directory. Also, in keeping with the convention for <abbr>(L)GPL</abbr>-licensed software, it has a separate file called <code>COPYING</code> which contains the complete text of the <abbr>LGPL</abbr>.
|
||||
|
||||
<pre class='nd screen'>
|
||||
chardet/
|
||||
|
|
||||
+--COPYING
|
||||
|
|
||||
+--setup.py
|
||||
|
|
||||
+--docs/
|
||||
| |
|
||||
| +--index.html
|
||||
| |
|
||||
| +--usage.html
|
||||
| |
|
||||
| +--...
|
||||
|
|
||||
+--chardet/
|
||||
|
|
||||
+--__init__.py
|
||||
|
|
||||
+--big5freq.py
|
||||
|
|
||||
+--...
|
||||
</code></pre>
|
||||
|
||||
<h2 id=setuppy>Writing Your Setup Script</h2>
|
||||
|
||||
@@ -155,7 +154,29 @@ A comprehensive HTTP client library, ``httplib2`` supports many features left ou
|
||||
|
||||
<p>This imports the <code>setup()</code> function, which is the main entry point into Distutils. 95% of all Distutils setup scripts consist of a single call to <code>setup()</code> and nothing else. (I totally just made up that statistic, but if your Distutils setup script is doing more than calling the Distutils <code>setup()</code> function, you should have a good reason.)
|
||||
|
||||
<p>...FIXME...required setup() parameters, optional but recommended setup() parameters, always use named parameters, etc.
|
||||
<p>The <code>setup()</code> function <a href=http://docs.python.org/3.1/distutils/apiref.html#distutils.core.setup>can take dozens of parameters</a>. For the sanity of everyone involved, you must use <a href=your-first-python-program.html#optional-arguments>named arguments</a> for every parameter. This is not merely a convention; it’s a hard requirement. Your setup script will crash if you try to call the <code>setup()</code> function with non-named arguments.
|
||||
|
||||
<p>The following named arguments are required:
|
||||
|
||||
<ul>
|
||||
<li><b>name</b>, the name of the package.
|
||||
<li><b>version</b>, the version number of the package.
|
||||
<li><b>author</b>, your full name.
|
||||
<li><b>author_email</b>, your email address.
|
||||
<li><b>url</b>, the home page of your project. This can be your <a href=http://pypi.python.org/>PyPI</a> package page if you don’t have a separate project website.
|
||||
</ul>
|
||||
|
||||
<p>Although not required, I recommend that you also include
|
||||
|
||||
<ul>
|
||||
<li><b>description</b>, a one-line summary of the project.
|
||||
<li><b>long_description</b>, a multi-line string in <a href=http://docutils.sourceforge.net/rst.html>reStructuredText format</a>. <a href=http://pypi.python.org/>PyPI</a> converts this to <abbr>HTML</abbr> and displays it on your package page.
|
||||
<li><b>classifiers</b>, a list of specially-formatted strings described in the next section.
|
||||
</ul>
|
||||
|
||||
<blockquote class=note>
|
||||
<p><span class=u>☞</span>Setup script metadata is defined in <a href=http://www.python.org/dev/peps/pep-0314/><abbr>PEP</abbr> 314</a>.
|
||||
</blockquote>
|
||||
|
||||
<h2 id=trove>Classifying Your Package</h2>
|
||||
|
||||
@@ -197,7 +218,7 @@ A comprehensive HTTP client library, ``httplib2`` supports many features left ou
|
||||
|
||||
<h3 id=trove-examples>Examples of Good Package Classifiers</h3>
|
||||
|
||||
<p>By way of example, here are the classifiers for <a href=http://pypi.python.org/pypi/Django/>Django</a>, a production-ready, cross-platform, <abbr>BSD</abbr>-licensed content management system that runs on your web server. (Django is not yet compatible with Python 3, so the <code>Programming Language :: Python :: Python 3</code> classifier is not listed.)
|
||||
<p>By way of example, here are the classifiers for <a href=http://pypi.python.org/pypi/Django/>Django</a>, a production-ready, cross-platform, <abbr>BSD</abbr>-licensed content management system that runs on your web server. (Django is not yet compatible with Python 3, so the <code>Programming Language :: Python :: 3</code> classifier is not listed.)
|
||||
|
||||
<pre><code>Programming Language :: Python
|
||||
License :: OSI Approved :: BSD License
|
||||
@@ -214,7 +235,7 @@ Topic :: Software Development :: Libraries :: Python Modules</code></pre>
|
||||
<p>Here are the classifiers for <a href=http://pypi.python.org/pypi/chardet><code>chardet</code></a>, the character encoding detection library covered in <a href=case-study-porting-chardet-to-python-3.html>Case Study: Porting <code>chardet</code> to Python 3</a>. <code>chardet</code> is beta quality, cross-platform, Python 3-compatible, <abbr>LGPL</abbr>-licensed, and intended for developers to integrate into their own products.
|
||||
|
||||
<pre><code>Programming Language :: Python
|
||||
Programming Language :: Python :: Python 3
|
||||
Programming Language :: Python :: 3
|
||||
License :: OSI Approved :: GNU Library or Lesser General Public License (LGPL)
|
||||
Operating System :: OS Independent
|
||||
Development Status :: 4 - Beta
|
||||
|
||||
Reference in New Issue
Block a user