diff --git a/CONTRIBUTORS.rst b/CONTRIBUTORS.rst index 778be7151..56efba356 100644 --- a/CONTRIBUTORS.rst +++ b/CONTRIBUTORS.rst @@ -27,6 +27,7 @@ Contributors (Pillow) - Sandro Mani - Simon Law - Stéphane Klein +- Steve Johnson - Takeshi KOMIYA - Tom Gross - Tom Payne diff --git a/README.rst b/README.rst index 5917d6a21..ce566acbb 100644 --- a/README.rst +++ b/README.rst @@ -16,6 +16,10 @@ Pillow is the "friendly" PIL fork by Alex Clark and Contributors. PIL is the Pyt :target: https://pypi.python.org/pypi/Pillow/ :alt: Number of PyPI downloads +The full documentation is hosted at http://pillow.readthedocs.org/. It +contains everything in this file plus tutorials, reference, compatibility +details, and more. + Introduction ------------ @@ -30,25 +34,10 @@ The fork author's goal is to foster active development of PIL through: - Regular releases to the `Python Package Index `_ - Solicitation for community contributions and involvement on `Image-SIG `_ -Why a fork? -~~~~~~~~~~~ +For information about why this fork exists and how it differs from PIL, see +`the About page in the documentation`_. -PIL is not setuptools compatible. Please see http://mail.python.org/pipermail/image-sig/2010-August/006480.html for a more detailed explanation. Also, PIL's current bi-yearly (or greater) release schedule is too infrequent to accomodate the large number and frequency of issues reported. - -What about the official PIL? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. Note:: Prior to Pillow 2.0.0, very few image code changes were made. Pillow 2.0.0 added Python 3 support and includes many bug fixes from many contributors. - -As more time passes since the last PIL release, the likelyhood of a new PIL release decreases. However, we've yet to hear an official "PIL is dead" announcement. So if you still want to support PIL, please report issues here first: - -- https://bitbucket.org/effbot/pil-2009-raclette/issues - -Then open a Pillow ticket here: - -- https://github.com/python-imaging/Pillow/issues - -Please provide a link to the PIL ticket so we can track the issue(s) upstream. +.. _the About page in the documentation: http://pillow.readthedocs.org/en/latest/about.html Installation ------------ @@ -69,11 +58,6 @@ Or download the compressed archive from PyPI, extract it, and inside it run:: For more information, please see http://pillow.readthedocs.org/en/latest/ or below. -Documentation -------------- - -The API documentation included with PIL has been converted (from HTML generated by pythondoc) to reStructured text (via pandoc) and is now `hosted by readthedocs.org `_. This is a work in progress: in order to re-generate new API documentation, either `pythondoc `_ will have to be run again or the pythondoc functionality must be converted to Sphinx. - Community Support ----------------- @@ -91,13 +75,13 @@ Financial Pillow is a volunteer effort led by Alex Clark. If you can't help with development, please help us financially; your assistance is very much needed and appreciated! -.. Note:: Contributors: please add your name and donation preference here. +.. Note:: Contributors: please add your name and donation preference here, as well as at the bottom of docs/index.rst. -+--------------------------------------+---------------------------------------+ -| **Developer** | **Preference** | -+--------------------------------------+---------------------------------------+ -| Alex Clark (fork author) | http://gittip.com/aclark4life | -+--------------------------------------+---------------------------------------+ +======================================= ======================================= +**Developer** **Preference** +======================================= ======================================= +Alex Clark (fork author) http://gittip.com/aclark4life +======================================= ======================================= Developer Notes --------------- @@ -205,358 +189,5 @@ Python Wheels Platform support ~~~~~~~~~~~~~~~~ -Current platform support for Pillow. Binary distributions are contributed for each release on a volunteer basis, but the source should compile and run everywhere platform support is listed. In general, we aim to support all current versions of Linux, OS X, and Windows. - -.. Note:: Contributors please test on your platform, edit this document and send a pull request - -+----------------------------------+-------------+------------------------------+------------------------------+-----------------------+ -|**Operating system** |**Supported**|**Tested Python versions** |**Tested Pillow versions** |**Tested processors** | -+----------------------------------+-------------+------------------------------+------------------------------+-----------------------+ -| CentOS 6.3 |Yes | 2.7,3.3 | |x86 | -+----------------------------------+-------------+------------------------------+------------------------------+-----------------------+ -| Mac OS X 10.8 Mountain Lion |Yes | 2.6,2.7,3.2,3.3 | |x86-64 | -+----------------------------------+-------------+------------------------------+------------------------------+-----------------------+ -| Mac OS X 10.7 Lion |Yes | 2.6,2.7,3.2,3.3 | 2.2.0 |x86-64 | -+----------------------------------+-------------+------------------------------+------------------------------+-----------------------+ -| Redhat Linux 6 |Yes | 2.6 | |x86 | -+----------------------------------+-------------+------------------------------+------------------------------+-----------------------+ -| Ubuntu Linux 10.04 LTS |Yes | 2.6 | 2.2.0 |x86,x86-64 | -+----------------------------------+-------------+------------------------------+------------------------------+-----------------------+ -| Ubuntu Linux 12.04 LTS |Yes | 2.6,2.7,3.2,3.3,PyPy2.1 | 2.2.0 |x86,x86-64 | -+----------------------------------+-------------+------------------------------+------------------------------+-----------------------+ -| Raspian Wheezy |Yes | 2.7,3.2 | 2.2.0 |arm | -+----------------------------------+-------------+------------------------------+------------------------------+-----------------------+ -| Gentoo Linux |Yes | 2.7,3.2 | 2.1.0 |x86-64 | -+----------------------------------+-------------+------------------------------+------------------------------+-----------------------+ -| Windows 7 Pro |Yes | 2.7,3.2 | |x86 | -+----------------------------------+-------------+------------------------------+------------------------------+-----------------------+ -| Windows Server 2008 R2 Enterprise|Yes | 3.3 | |x86-64 | -+----------------------------------+-------------+------------------------------+------------------------------+-----------------------+ -| Windows 8 Pro |Yes | 2.6,2.7,3.2,3.3,3.4a3 | 2.2.0 |x86,x86-64 | -+----------------------------------+-------------+------------------------------+------------------------------+-----------------------+ - - -Port existing PIL-based code to Pillow -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Pillow is a functional drop-in replacement for the Python Imaging Library. To run your existing PIL-compatible code with Pillow, it needs to be modified to import the ``Imaging`` module from the ``PIL`` namespace *instead* of the global namespace. I.e. change:: - - import Image - -to:: - - from PIL import Image - -.. Note:: If your code imports from ``_imaging``, it will no longer work. - -The preferred, future proof method of importing the private ``_imaging`` module is:: - - from PIL import Image - _imaging = Image.core - -Python Imaging Library -====================== - -.. Note:: What follows is the original PIL 1.1.7 README file contents. - -:: - - The Python Imaging Library - $Id$ - - Release 1.1.7 (November 15, 2009) - - ==================================================================== - The Python Imaging Library 1.1.7 - ==================================================================== - - Contents - -------- - - + Introduction - + Support Options - - Commercial support - - Free support - + Software License - + Build instructions (all platforms) - - Additional notes for Mac OS X - - Additional notes for Windows - - -------------------------------------------------------------------- - Introduction - -------------------------------------------------------------------- - - The Python Imaging Library (PIL) adds image processing capabilities - to your Python environment. This library provides extensive file - format support, an efficient internal representation, and powerful - image processing capabilities. - - This source kit has been built and tested with Python 2.0 and newer, - on Windows, Mac OS X, and major Unix platforms. Large parts of the - library also work on 1.5.2 and 1.6. - - The main distribution site for this software is: - - http://www.pythonware.com/products/pil/ - - That site also contains information about free and commercial support - options, PIL add-ons, answers to frequently asked questions, and more. - - - Development versions (alphas, betas) are available here: - - http://effbot.org/downloads/ - - - The PIL handbook is not included in this distribution; to get the - latest version, check: - - http://www.pythonware.com/library/ - http://effbot.org/books/imagingbook/ (drafts) - - - For installation and licensing details, see below. - - - -------------------------------------------------------------------- - Support Options - -------------------------------------------------------------------- - - + Commercial Support - - Secret Labs (PythonWare) offers support contracts for companies using - the Python Imaging Library in commercial applications, and in mission- - critical environments. The support contract includes technical support, - bug fixes, extensions to the PIL library, sample applications, and more. - - For the full story, check: - - http://www.pythonware.com/products/pil/support.htm - - - + Free Support - - For support and general questions on the Python Imaging Library, send - e-mail to the Image SIG mailing list: - - image-sig@python.org - - You can join the Image SIG by sending a mail to: - - image-sig-request@python.org - - Put "subscribe" in the message body to automatically subscribe to the - list, or "help" to get additional information. Alternatively, you can - send your questions to the Python mailing list, python-list@python.org, - or post them to the newsgroup comp.lang.python. DO NOT SEND SUPPORT - QUESTIONS TO PYTHONWARE ADDRESSES. - - - -------------------------------------------------------------------- - Software License - -------------------------------------------------------------------- - - The Python Imaging Library is - - Copyright (c) 1997-2009 by Secret Labs AB - Copyright (c) 1995-2009 by Fredrik Lundh - - By obtaining, using, and/or copying this software and/or its - associated documentation, you agree that you have read, understood, - and will comply with the following terms and conditions: - - Permission to use, copy, modify, and distribute this software and its - associated documentation for any purpose and without fee is hereby - granted, provided that the above copyright notice appears in all - copies, and that both that copyright notice and this permission notice - appear in supporting documentation, and that the name of Secret Labs - AB or the author not be used in advertising or publicity pertaining to - distribution of the software without specific, written prior - permission. - - SECRET LABS AB AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO - THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND - FITNESS. IN NO EVENT SHALL SECRET LABS AB OR THE AUTHOR BE LIABLE FOR - ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES - WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN - ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT - OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. - - - -------------------------------------------------------------------- - Build instructions (all platforms) - -------------------------------------------------------------------- - - For a list of changes in this release, see the CHANGES document. - - 0. If you're in a hurry, try this: - - $ tar xvfz Imaging-1.1.7.tar.gz - $ cd Imaging-1.1.7 - $ python setup.py install - - If you prefer to know what you're doing, read on. - - - 1. Prerequisites. - - If you need any of the features described below, make sure you - have the necessary libraries before building PIL. - - feature library - ----------------------------------------------------------------- - JPEG support libjpeg (6a or 6b) - - http://www.ijg.org - http://www.ijg.org/files/jpegsrc.v6b.tar.gz - ftp://ftp.uu.net/graphics/jpeg/ - - PNG support zlib (1.2.3 or later is recommended) - - http://www.gzip.org/zlib/ - - OpenType/TrueType freetype2 (2.3.9 or later is recommended) - support - http://www.freetype.org - http://freetype.sourceforge.net - - CMS support littleCMS (1.1.5 or later is recommended) - support - http://www.littlecms.com/ - - If you have a recent Linux version, the libraries provided with the - operating system usually work just fine. If some library is - missing, installing a prebuilt version (jpeg-devel, zlib-devel, - etc) is usually easier than building from source. For example, for - Ubuntu 9.10 (karmic), you can install the following libraries: - - sudo apt-get install libjpeg62-dev - sudo apt-get install zlib1g-dev - sudo apt-get install libfreetype6-dev - sudo apt-get install liblcms1-dev - - If you're using Mac OS X, you can use the 'fink' tool to install - missing libraries (also see the Mac OS X section below). - - Similar tools are available for many other platforms. - - - 2. To build under Python 1.5.2, you need to install the stand-alone - version of the distutils library: - - http://www.python.org/sigs/distutils-sig/download.html - - You can fetch distutils 1.0.2 from the Python source repository: - - svn export http://svn.python.org/projects/python/tags/Distutils-1_0_2/Lib/distutils/ - - For newer releases, the distutils library is included in the - Python standard library. - - NOTE: Version 1.1.7 is not fully compatible with 1.5.2. Some - more recent additions to the library may not work, but the core - functionality is available. - - - 3. If you didn't build Python from sources, make sure you have - Python's build support files on your machine. If you've down- - loaded a prebuilt package (e.g. a Linux RPM), you probably - need additional developer packages. Look for packages named - "python-dev", "python-devel", or similar. For example, for - Ubuntu 9.10 (karmic), use the following command: - - sudo apt-get install python-dev - - - 4. When you have everything you need, unpack the PIL distribution - (the file Imaging-1.1.7.tar.gz) in a suitable work directory: - - $ cd MyExtensions # example - $ gunzip Imaging-1.1.7.tar.gz - $ tar xvf Imaging-1.1.7.tar - - - 5. Build the library. We recommend that you do an in-place build, - and run the self test before installing. - - $ cd Imaging-1.1.7 - $ python setup.py build_ext -i - $ python selftest.py - - During the build process, the setup.py will display a summary - report that lists what external components it found. The self- - test will display a similar report, with what external components - the tests found in the actual build files: - - ---------------------------------------------------------------- - PIL 1.1.7 SETUP SUMMARY - ---------------------------------------------------------------- - *** TKINTER support not available (Tcl/Tk 8.5 libraries needed) - --- JPEG support available - --- ZLIB (PNG/ZIP) support available - --- FREETYPE support available - ---------------------------------------------------------------- - - Make sure that the optional components you need are included. - - If the build script won't find a given component, you can edit the - setup.py file and set the appropriate ROOT variable. For details, - see instructions in the file. - - If the build script finds the component, but the tests cannot - identify it, try rebuilding *all* modules: - - $ python setup.py clean - $ python setup.py build_ext -i - - - 6. If the setup.py and selftest.py commands finish without any - errors, you're ready to install the library: - - $ python setup.py install - - (depending on how Python has been installed on your machine, - you might have to log in as a superuser to run the 'install' - command, or use the 'sudo' command to run 'install'.) - - - -------------------------------------------------------------------- - Additional notes for Mac OS X - -------------------------------------------------------------------- - - On Mac OS X you will usually install additional software such as - libjpeg or freetype with the "fink" tool, and then it ends up in - "/sw". If you have installed the libraries elsewhere, you may have - to tweak the "setup.py" file before building. - - - -------------------------------------------------------------------- - Additional notes for Windows - -------------------------------------------------------------------- - - On Windows, you need to tweak the ROOT settings in the "setup.py" - file, to make it find the external libraries. See comments in the - file for details. - - Make sure to build PIL and the external libraries with the same - runtime linking options as was used for the Python interpreter - (usually /MD, under Visual Studio). - - - Note that most Python distributions for Windows include libraries - compiled for Microsoft Visual Studio. You can get the free Express - edition of Visual Studio from: - - http://www.microsoft.com/Express/ - - To build extensions using other tool chains, see the "Using - non-Microsoft compilers on Windows" section in the distutils handbook: - - http://www.python.org/doc/current/inst/non-ms-compilers.html - - For additional information on how to build extensions using the - popular MinGW compiler, see: - - http://mingw.org (compiler) - http://sebsauvage.net/python/mingw.html (build instructions) - http://sourceforge.net/projects/gnuwin32 (prebuilt libraries) +Current platform support for Pillow is documented here: +http://pillow.readthedocs.org/en/latest/installation.html#platform-support diff --git a/docs/Guardfile b/docs/Guardfile index 2bbb2ef91..f8f3051ed 100644 --- a/docs/Guardfile +++ b/docs/Guardfile @@ -5,5 +5,6 @@ from livereload.compiler import shell Task.add('*.rst', shell('make html')) Task.add('*/*.rst', shell('make html')) Task.add('_static/*.css', shell('make clean html')) +Task.add('_templates/*', shell('make clean html')) Task.add('Makefile', shell('make html')) Task.add('conf.py', shell('make html')) diff --git a/docs/_templates/sidebarhelp.html b/docs/_templates/sidebarhelp.html new file mode 100644 index 000000000..330b3de45 --- /dev/null +++ b/docs/_templates/sidebarhelp.html @@ -0,0 +1,18 @@ +

Need help?

+ +

+ You can seek realtime assistance via IRC at + irc://irc.freenode.net#pil. You can + also post to the + + Image-SIG mailing list. And, of course, there's + + Stack Overflow. +

+ +

+ If you've discovered a bug, you can + open an issue + on Github. +

+ diff --git a/docs/about.rst b/docs/about.rst new file mode 100644 index 000000000..dfd88b605 --- /dev/null +++ b/docs/about.rst @@ -0,0 +1,47 @@ +About Pillow +============ + +Goals +----- + +The fork authors' goal is to foster active development of PIL through: + +- Continuous integration testing via `Travis CI`_ +- Publicized development activity on `GitHub`_ +- Regular releases to the `Python Package Index`_ +- Solicitation for community contributions and involvement on `Image-SIG`_ + +.. _Travis CI: https://travis-ci.org/python-imaging/Pillow +.. _GitHub: https://github.com/python-imaging/Pillow +.. _Python Package Index: https://pypi.python.org/pypi/Pillow +.. _Image-SIG: http://mail.python.org/mailman/listinfo/image-sig + +Why a fork? +----------- + +PIL is not setuptools compatible. Please see `this Image-SIG post`_ for a more +detailed explanation. Also, PIL's current bi-yearly (or greater) release +schedule is too infrequent to accomodate the large number and frequency of +issues reported. + +.. _this Image-SIG post: https://mail.python.org/pipermail/image-sig/2010-August/006480.html + +What about the official PIL? +---------------------------- + +.. note:: + + Prior to Pillow 2.0.0, very few image code changes were made. Pillow 2.0.0 + added Python 3 support and includes many bug fixes from many contributors. + +As more time passes since the last PIL release, the likelyhood of a new PIL +release decreases. However, we've yet to hear an official "PIL is dead" +announcement. So if you still want to support PIL, please +`report issues here first`_, then +`open the corresponding Pillow tickets here`_. + +.. _report issues here first: https://bitbucket.org/effbot/pil-2009-raclette/issues + +.. _open the corresponding Pillow tickets here: https://github.com/python-imaging/Pillow/issues + +Please provide a link to the PIL ticket so we can track the issue(s) upstream. diff --git a/docs/conf.py b/docs/conf.py index a9ae431bb..987b6dbb3 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,96 +1,39 @@ # -*- coding: utf-8 -*- -# -# Pillow (PIL fork) documentation build configuration file, created by -# sphinx-quickstart on Fri Apr 12 19:51:26 2013. -# -# This file is execfile()d with the current directory set to its containing dir. -# -# Note that not all possible configuration values are present in this -# autogenerated file. -# -# All configuration values have a default; values that are commented out -# serve to show the default. +import os +import sys -import sys, os - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. sys.path.insert(0, os.path.abspath('../')) import PIL -# -- General configuration ----------------------------------------------------- +### general configuration ### -# If your documentation needs a minimal Sphinx version, state it here. -#needs_sphinx = '1.0' +needs_sphinx = '1.0' -# Add any Sphinx extension module names here, as strings. They can be extensions -# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode', 'sphinx.ext.intersphinx'] intersphinx_mapping = {'http://docs.python.org/2/': None} -# Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] - -# The suffix of source filenames. source_suffix = '.rst' - -# The encoding of source files. +templates_path = ['_templates'] #source_encoding = 'utf-8-sig' - -# The master toctree document. master_doc = 'index' -# General information about the project. project = u'Pillow (PIL fork)' -copyright = u'1997-2011 by Secret Labs AB, 1995-2011 by Fredrik Lundh, 2010-2013 Alex Clark' +copyright = (u'1997-2011 by Secret Labs AB,' + u' 1995-2011 by Fredrik Lundh, 2010-2013 Alex Clark') -# The version info for the project you're documenting, acts as replacement for -# |version| and |release|, also used in various other places throughout the -# built documents. -# # The short X.Y version. version = PIL.PILLOW_VERSION # The full version, including alpha/beta/rc tags. release = version -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -#language = None - -# There are two options for replacing |today|: either, you set today to some -# non-false value, then it is used: -#today = '' -# Else, today_fmt is used as the format for a strftime call. -#today_fmt = '%B %d, %Y' - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. +# currently excluding autodoc'd plugs exclude_patterns = ['_build', 'plugins.rst'] -# The reST default role (used for this markup: `text`) to use for all documents. -#default_role = None - -# If true, '()' will be appended to :func: etc. cross-reference text. -#add_function_parentheses = True - -# If true, the current module name will be prepended to all description -# unit titles (such as .. function::). -#add_module_names = True - -# If true, sectionauthor and moduleauthor directives will be shown in the -# output. They are ignored by default. -#show_authors = False - # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' -# A list of ignored prefixes for module index sorting. -#modindex_common_prefix = [] - - -# -- Options for HTML output --------------------------------------------------- +### HTML output ### from better import better_theme_path html_theme_path = [better_theme_path] @@ -100,140 +43,27 @@ html_title = "Pillow v{release} (PIL fork)".format(release=release) html_short_title = "Home" html_static_path = ['_static'] -# Theme options are theme-specific and customize the look and feel of a theme -# further. For a list of options available for each theme, see the -# documentation. html_theme_options = {} html_sidebars = { - '**': ['localtoc.html', 'sourcelink.html', 'searchbox.html'], - 'index': ['searchbox.html'], + '**': ['localtoc.html', 'sourcelink.html', 'sidebarhelp.html', + 'searchbox.html'], + 'index': ['globaltoc.html', 'sidebarhelp.html', 'searchbox.html'], } -# The name for this set of Sphinx documents. If None, it defaults to -# " v documentation". -#html_title = None - # Output file base name for HTML help builder. -htmlhelp_basename = 'PillowPILforkdoc' +htmlhelp_basename = 'Pillowdoc' -# -- Options for LaTeX output -------------------------------------------------- +### LaTeX output (RtD PDF output as well) ### -latex_elements = { -# The paper size ('letterpaper' or 'a4paper'). -#'papersize': 'letterpaper', +latex_elements = {} -# The font size ('10pt', '11pt' or '12pt'). -#'pointsize': '10pt', - -# Additional stuff for the LaTeX preamble. -#'preamble': '', -} - -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, author, documentclass [howto/manual]). latex_documents = [ - ('index', 'PillowPILfork.tex', u'Pillow (PIL fork) Documentation', - u'Author', 'manual'), + ('index', 'Pillow.tex', u'Pillow (PIL fork) Documentation', u'Author', + 'manual'), ] -# The name of an image file (relative to this directory) to place at the top of -# the title page. -#latex_logo = None - -# For "manual" documents, if this is true, then toplevel headings are parts, -# not chapters. -#latex_use_parts = False - -# If true, show page references after internal links. -#latex_show_pagerefs = False - -# If true, show URL addresses after external links. -#latex_show_urls = False - -# Documents to append as an appendix to all manuals. -#latex_appendices = [] - -# If false, no module index is generated. -#latex_domain_indices = True - - -# -- Options for manual page output -------------------------------------------- - -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). -man_pages = [ - ('index', 'pillowpilfork', u'Pillow (PIL fork) Documentation', - [u'Author'], 1) -] - -# If true, show URL addresses after external links. -#man_show_urls = False - - -# -- Options for Texinfo output ------------------------------------------------ - -# Grouping the document tree into Texinfo files. List of tuples -# (source start file, target name, title, author, -# dir menu entry, description, category) -texinfo_documents = [ - ('index', 'PillowPILfork', u'Pillow (PIL fork) Documentation', - u'Author', 'PillowPILfork', 'One line description of project.', - 'Miscellaneous'), -] - -# Documents to append as an appendix to all manuals. -#texinfo_appendices = [] - -# If false, no module index is generated. -#texinfo_domain_indices = True - -# How to display URL addresses: 'footnote', 'no', or 'inline'. -#texinfo_show_urls = 'footnote' - - -# -- Options for Epub output --------------------------------------------------- - -# Bibliographic Dublin Core info. -epub_title = u'Pillow (PIL fork)' -epub_author = u'Author' -epub_publisher = u'Author' -epub_copyright = u'2013, Author' - -# The language of the text. It defaults to the language option -# or en if the language is not set. -#epub_language = '' - -# The scheme of the identifier. Typical schemes are ISBN or URL. -#epub_scheme = '' - -# The unique identifier of the text. This can be a ISBN number -# or the project homepage. -#epub_identifier = '' - -# A unique identification for the text. -#epub_uid = '' - -# A tuple containing the cover image and cover page html template filenames. -#epub_cover = () - -# HTML files that should be inserted before the pages created by sphinx. -# The format is a list of tuples containing the path and title. -#epub_pre_files = [] - -# HTML files shat should be inserted after the pages created by sphinx. -# The format is a list of tuples containing the path and title. -#epub_post_files = [] - -# A list of files that should not be packed into the epub file. -#epub_exclude_files = [] - -# The depth of the table of contents in toc.ncx. -#epub_tocdepth = 3 - -# Allow duplicate toc entries. -#epub_tocdup = True # skip_api_docs setting will skip PIL.rst if True. Used for working on the # guides; makes livereload basically instantaneous. diff --git a/docs/guides.rst b/docs/guides.rst new file mode 100644 index 000000000..926d3cfcc --- /dev/null +++ b/docs/guides.rst @@ -0,0 +1,10 @@ +Guides +====== + +.. toctree:: + :maxdepth: 2 + + handbook/overview + handbook/tutorial + handbook/concepts + porting-pil-to-pillow diff --git a/docs/handbook/guides.rst b/docs/handbook/guides.rst deleted file mode 100644 index edec8bea8..000000000 --- a/docs/handbook/guides.rst +++ /dev/null @@ -1,9 +0,0 @@ -Guides -====== - -.. toctree:: - :maxdepth: 2 - - overview - tutorial - concepts diff --git a/docs/index.rst b/docs/index.rst index 883b1bdb3..9dad0ec4f 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -4,24 +4,64 @@ Pillow: a modern fork of PIL Pillow is the "friendly" PIL fork by Alex Clark and Contributors. PIL is the Python Imaging Library by Fredrik Lundh and Contributors. -Pillow >= 2.0.0 supports Python versions 2.6, 2.7, 3.2, 3.3. +.. image:: https://travis-ci.org/python-imaging/Pillow.png + :target: https://travis-ci.org/python-imaging/Pillow -Pillow < 2.0.0 supports Python versions 2.4, 2.5, 2.6, 2.7. +.. image:: https://pypip.in/v/Pillow/badge.png + :target: https://pypi.python.org/pypi/Pillow/ + :alt: Latest PyPI version + +.. image:: https://pypip.in/d/Pillow/badge.png + :target: https://pypi.python.org/pypi/Pillow/ + :alt: Number of PyPI downloads + +.. note:: Pillow >= 2.0.0 supports Python versions 2.6, 2.7, 3.2, 3.3. + +.. note:: Pillow < 2.0.0 supports Python versions 2.4, 2.5, 2.6, 2.7. + +For full compatibility, you'll want to read the complete :doc:`installation +instructions `. -For general information including installation instructions, see `README.rst`_. If you can't find the information you need, try the old `PIL Handbook`_, but be -aware that it was last updated for PIL 1.1.5. +aware that it was last updated for PIL 1.1.5. You can download archives and old +versions from `PyPI `_. You can get the +source and contribute at https://github.com/python-imaging/Pillow. -.. _README.rst: https://github.com/python-imaging/Pillow/blob/master/README.rst .. _PIL Handbook: http://effbot.org/imagingbook/pil-index.htm .. toctree:: :maxdepth: 2 - handbook/guides.rst - handbook/appendices.rst + installation + about + guides + handbook/appendices PIL - plugins + original-readme + +Support Pillow! +=============== + +PIL needs you! Please help us maintain the Python Imaging Library here: + +- `GitHub `_ +- `Freenode `_ +- `Image-SIG `_ + +Financial +--------- + +Pillow is a volunteer effort led by Alex Clark. If you can't help with +development, please help us financially; your assistance is very much needed +and appreciated! + +.. note:: Contributors: please add your name and donation preference here. + +======================================= ======================================= +**Developer** **Preference** +======================================= ======================================= +Alex Clark (fork author) http://gittip.com/aclark4life +======================================= ======================================= Indices and tables ================== diff --git a/docs/installation.rst b/docs/installation.rst new file mode 100644 index 000000000..0a9934bf9 --- /dev/null +++ b/docs/installation.rst @@ -0,0 +1,191 @@ +Installation +============ + +.. warning:: PIL and Pillow currently cannot co-exist in the same environment. + If you want to use Pillow, please remove PIL first. + +Simple installation +------------------- + +.. note:: + + The following instructions will install Pillow with support for most formats. + See :ref:`external-libraries` for the features you would gain by installing + the external libraries first. This page probably also include specific + instructions for your platform. + +You can install Pillow with :command:`pip`:: + + $ pip install Pillow + +Or :command:`easy_install` (for installing `Python Eggs +`_, as :command:`pip` does +not support them):: + + $ easy_install Pillow + +Or download the `compressed archive from PyPI`_, extract it, and inside it +run:: + + $ python setup.py install + +.. _compressed archive from PyPI: https://pypi.python.org/pypi/Pillow + +.. _external-libraries: + +External libraries +------------------ + +Many of Pillow's features require external libraries: + +* **libjpeg** provides JPEG functionality. + + * Pillow has been tested with libjpeg versions **6b**, **8**, and **9** + +* **zlib** provides access to compressed PNGs + +* **libtiff** provides group4 tiff functionality + + * Pillow has been tested with libtiff versions **3.x** and **4.0** + +* **libfreetype** provides type related services + +* **littlecms** provides color management + +* **libwebp** provides the Webp format. + + * Pillow has been tested with version **0.1.3**, which does not read transparent webp files. Version **0.3.0** supports transparency. + +* **tcl/tk** provides support for tkinter bitmap and photo images. + +If the prerequisites are installed in the standard library locations for your +machine (e.g. :file:`/usr` or :file:`/usr/local`), no additional configuration +should be required. If they are installed in a non-standard location, you may +need to configure setuptools to use those locations (i.e. by editing +:file:`setup.py` and/or :file:`setup.cfg`). Once you have installed the +prerequisites, run:: + + $ pip install Pillow + +Linux installation +------------------ + +.. note:: + + Fedora, Debian/Ubuntu, and ArchLinux include Pillow (instead of PIL) with + their distributions. Consider using those instead of installing manually. + +.. note:: + + You *do not* need to install all of the external libraries to get Pillow's + basics to work. + +**We do not provide binaries for Linux.** If you didn't build Python from +source, make sure you have Python's development libraries installed. In Debian +or Ubuntu:: + + $ sudo apt-get install python-dev python-setuptools + +Or for Python 3:: + + $ sudo apt-get install python3-dev python3-setuptools + +Prerequisites are installed on **Ubuntu 10.04 LTS** with:: + + $ sudo apt-get install libtiff4-dev libjpeg62-dev zlib1g-dev \ + libfreetype6-dev liblcms1-dev tcl8.5-dev tk8.5-dev + +Prerequisites are installed with on **Ubuntu 12.04 LTS** or **Raspian Wheezy +7.0** with:: + + $ sudo apt-get install libtiff4-dev libjpeg8-dev zlib1g-dev \ + libfreetype6-dev liblcms1-dev libwebp-dev tcl8.5-dev tk8.5-dev + +Mac OS X installation +--------------------- + +.. note:: + + You *do not* need to install all of the external libraries to get Pillow's + basics to work. + +**We do not provide binaries for OS X**, so you'll need XCode to install +Pillow. (XCode 4.2 on 10.6 will work with the Official Python binary +distribution. Otherwise, use whatever XCode you used to compile Python.) + +The easiest way to install the prerequisites is via `Homebrew +`_. After you install Homebrew, run:: + + $ brew install libtiff libjpeg webp littlecms + +If you've built your own Python, then you should be able to install Pillow +using:: + + $ pip install Pillow + +Windows installation +-------------------- + +We provide binaries for Windows in the form of Python Eggs and `Python Wheels +`_: + +Python Eggs +^^^^^^^^^^^ + +.. note:: + + :command:`pip` does not support Python Eggs; use :command:`easy_install` + instead. + +:: + + $ easy_install Pillow + +Python Wheels +^^^^^^^^^^^^^ + +.. Note:: Experimental. Requires setuptools >=0.8 and pip >=1.4.1 + +:: + + $ pip install --use-wheel Pillow + +Platform support +---------------- + +Current platform support for Pillow. Binary distributions are contributed for +each release on a volunteer basis, but the source should compile and run +everywhere platform support is listed. In general, we aim to support all +current versions of Linux, OS X, and Windows. + +.. note:: + + Contributors please test on your platform, edit this document, and send a + pull request. + ++----------------------------------+-------------+------------------------------+------------------------------+-----------------------+ +|**Operating system** |**Supported**|**Tested Python versions** |**Tested Pillow versions** |**Tested processors** | ++----------------------------------+-------------+------------------------------+------------------------------+-----------------------+ +| CentOS 6.3 |Yes | 2.7,3.3 | |x86 | ++----------------------------------+-------------+------------------------------+------------------------------+-----------------------+ +| Mac OS X 10.8 Mountain Lion |Yes | 2.6,2.7,3.2,3.3 | |x86-64 | ++----------------------------------+-------------+------------------------------+------------------------------+-----------------------+ +| Mac OS X 10.7 Lion |Yes | 2.6,2.7,3.2,3.3 | 2.2.0 |x86-64 | ++----------------------------------+-------------+------------------------------+------------------------------+-----------------------+ +| Redhat Linux 6 |Yes | 2.6 | |x86 | ++----------------------------------+-------------+------------------------------+------------------------------+-----------------------+ +| Ubuntu Linux 10.04 LTS |Yes | 2.6 | 2.2.0 |x86,x86-64 | ++----------------------------------+-------------+------------------------------+------------------------------+-----------------------+ +| Ubuntu Linux 12.04 LTS |Yes | 2.6,2.7,3.2,3.3,PyPy2.1 | 2.2.0 |x86,x86-64 | ++----------------------------------+-------------+------------------------------+------------------------------+-----------------------+ +| Raspian Wheezy |Yes | 2.7,3.2 | 2.2.0 |arm | ++----------------------------------+-------------+------------------------------+------------------------------+-----------------------+ +| Gentoo Linux |Yes | 2.7,3.2 | 2.1.0 |x86-64 | ++----------------------------------+-------------+------------------------------+------------------------------+-----------------------+ +| Windows 7 Pro |Yes | 2.7,3.2 | |x86 | ++----------------------------------+-------------+------------------------------+------------------------------+-----------------------+ +| Windows Server 2008 R2 Enterprise|Yes | 3.3 | |x86-64 | ++----------------------------------+-------------+------------------------------+------------------------------+-----------------------+ +| Windows 8 Pro |Yes | 2.6,2.7,3.2,3.3,3.4a3 | 2.2.0 |x86,x86-64 | ++----------------------------------+-------------+------------------------------+------------------------------+-----------------------+ + diff --git a/docs/original-readme.rst b/docs/original-readme.rst new file mode 100644 index 000000000..73b941f37 --- /dev/null +++ b/docs/original-readme.rst @@ -0,0 +1,306 @@ +Original PIL README +=================== + +What follows is the original PIL 1.1.7 README file contents. + +:: + + The Python Imaging Library + $Id$ + + Release 1.1.7 (November 15, 2009) + + ==================================================================== + The Python Imaging Library 1.1.7 + ==================================================================== + + Contents + -------- + + + Introduction + + Support Options + - Commercial support + - Free support + + Software License + + Build instructions (all platforms) + - Additional notes for Mac OS X + - Additional notes for Windows + + -------------------------------------------------------------------- + Introduction + -------------------------------------------------------------------- + + The Python Imaging Library (PIL) adds image processing capabilities + to your Python environment. This library provides extensive file + format support, an efficient internal representation, and powerful + image processing capabilities. + + This source kit has been built and tested with Python 2.0 and newer, + on Windows, Mac OS X, and major Unix platforms. Large parts of the + library also work on 1.5.2 and 1.6. + + The main distribution site for this software is: + + http://www.pythonware.com/products/pil/ + + That site also contains information about free and commercial support + options, PIL add-ons, answers to frequently asked questions, and more. + + + Development versions (alphas, betas) are available here: + + http://effbot.org/downloads/ + + + The PIL handbook is not included in this distribution; to get the + latest version, check: + + http://www.pythonware.com/library/ + http://effbot.org/books/imagingbook/ (drafts) + + + For installation and licensing details, see below. + + + -------------------------------------------------------------------- + Support Options + -------------------------------------------------------------------- + + + Commercial Support + + Secret Labs (PythonWare) offers support contracts for companies using + the Python Imaging Library in commercial applications, and in mission- + critical environments. The support contract includes technical support, + bug fixes, extensions to the PIL library, sample applications, and more. + + For the full story, check: + + http://www.pythonware.com/products/pil/support.htm + + + + Free Support + + For support and general questions on the Python Imaging Library, send + e-mail to the Image SIG mailing list: + + image-sig@python.org + + You can join the Image SIG by sending a mail to: + + image-sig-request@python.org + + Put "subscribe" in the message body to automatically subscribe to the + list, or "help" to get additional information. Alternatively, you can + send your questions to the Python mailing list, python-list@python.org, + or post them to the newsgroup comp.lang.python. DO NOT SEND SUPPORT + QUESTIONS TO PYTHONWARE ADDRESSES. + + + -------------------------------------------------------------------- + Software License + -------------------------------------------------------------------- + + The Python Imaging Library is + + Copyright (c) 1997-2009 by Secret Labs AB + Copyright (c) 1995-2009 by Fredrik Lundh + + By obtaining, using, and/or copying this software and/or its + associated documentation, you agree that you have read, understood, + and will comply with the following terms and conditions: + + Permission to use, copy, modify, and distribute this software and its + associated documentation for any purpose and without fee is hereby + granted, provided that the above copyright notice appears in all + copies, and that both that copyright notice and this permission notice + appear in supporting documentation, and that the name of Secret Labs + AB or the author not be used in advertising or publicity pertaining to + distribution of the software without specific, written prior + permission. + + SECRET LABS AB AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO + THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND + FITNESS. IN NO EVENT SHALL SECRET LABS AB OR THE AUTHOR BE LIABLE FOR + ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES + WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN + ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT + OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + + + -------------------------------------------------------------------- + Build instructions (all platforms) + -------------------------------------------------------------------- + + For a list of changes in this release, see the CHANGES document. + + 0. If you're in a hurry, try this: + + $ tar xvfz Imaging-1.1.7.tar.gz + $ cd Imaging-1.1.7 + $ python setup.py install + + If you prefer to know what you're doing, read on. + + + 1. Prerequisites. + + If you need any of the features described below, make sure you + have the necessary libraries before building PIL. + + feature library + ----------------------------------------------------------------- + JPEG support libjpeg (6a or 6b) + + http://www.ijg.org + http://www.ijg.org/files/jpegsrc.v6b.tar.gz + ftp://ftp.uu.net/graphics/jpeg/ + + PNG support zlib (1.2.3 or later is recommended) + + http://www.gzip.org/zlib/ + + OpenType/TrueType freetype2 (2.3.9 or later is recommended) + support + http://www.freetype.org + http://freetype.sourceforge.net + + CMS support littleCMS (1.1.5 or later is recommended) + support + http://www.littlecms.com/ + + If you have a recent Linux version, the libraries provided with the + operating system usually work just fine. If some library is + missing, installing a prebuilt version (jpeg-devel, zlib-devel, + etc) is usually easier than building from source. For example, for + Ubuntu 9.10 (karmic), you can install the following libraries: + + sudo apt-get install libjpeg62-dev + sudo apt-get install zlib1g-dev + sudo apt-get install libfreetype6-dev + sudo apt-get install liblcms1-dev + + If you're using Mac OS X, you can use the 'fink' tool to install + missing libraries (also see the Mac OS X section below). + + Similar tools are available for many other platforms. + + + 2. To build under Python 1.5.2, you need to install the stand-alone + version of the distutils library: + + http://www.python.org/sigs/distutils-sig/download.html + + You can fetch distutils 1.0.2 from the Python source repository: + + svn export http://svn.python.org/projects/python/tags/Distutils-1_0_2/Lib/distutils/ + + For newer releases, the distutils library is included in the + Python standard library. + + NOTE: Version 1.1.7 is not fully compatible with 1.5.2. Some + more recent additions to the library may not work, but the core + functionality is available. + + + 3. If you didn't build Python from sources, make sure you have + Python's build support files on your machine. If you've down- + loaded a prebuilt package (e.g. a Linux RPM), you probably + need additional developer packages. Look for packages named + "python-dev", "python-devel", or similar. For example, for + Ubuntu 9.10 (karmic), use the following command: + + sudo apt-get install python-dev + + + 4. When you have everything you need, unpack the PIL distribution + (the file Imaging-1.1.7.tar.gz) in a suitable work directory: + + $ cd MyExtensions # example + $ gunzip Imaging-1.1.7.tar.gz + $ tar xvf Imaging-1.1.7.tar + + + 5. Build the library. We recommend that you do an in-place build, + and run the self test before installing. + + $ cd Imaging-1.1.7 + $ python setup.py build_ext -i + $ python selftest.py + + During the build process, the setup.py will display a summary + report that lists what external components it found. The self- + test will display a similar report, with what external components + the tests found in the actual build files: + + ---------------------------------------------------------------- + PIL 1.1.7 SETUP SUMMARY + ---------------------------------------------------------------- + *** TKINTER support not available (Tcl/Tk 8.5 libraries needed) + --- JPEG support available + --- ZLIB (PNG/ZIP) support available + --- FREETYPE support available + ---------------------------------------------------------------- + + Make sure that the optional components you need are included. + + If the build script won't find a given component, you can edit the + setup.py file and set the appropriate ROOT variable. For details, + see instructions in the file. + + If the build script finds the component, but the tests cannot + identify it, try rebuilding *all* modules: + + $ python setup.py clean + $ python setup.py build_ext -i + + + 6. If the setup.py and selftest.py commands finish without any + errors, you're ready to install the library: + + $ python setup.py install + + (depending on how Python has been installed on your machine, + you might have to log in as a superuser to run the 'install' + command, or use the 'sudo' command to run 'install'.) + + + -------------------------------------------------------------------- + Additional notes for Mac OS X + -------------------------------------------------------------------- + + On Mac OS X you will usually install additional software such as + libjpeg or freetype with the "fink" tool, and then it ends up in + "/sw". If you have installed the libraries elsewhere, you may have + to tweak the "setup.py" file before building. + + + -------------------------------------------------------------------- + Additional notes for Windows + -------------------------------------------------------------------- + + On Windows, you need to tweak the ROOT settings in the "setup.py" + file, to make it find the external libraries. See comments in the + file for details. + + Make sure to build PIL and the external libraries with the same + runtime linking options as was used for the Python interpreter + (usually /MD, under Visual Studio). + + + Note that most Python distributions for Windows include libraries + compiled for Microsoft Visual Studio. You can get the free Express + edition of Visual Studio from: + + http://www.microsoft.com/Express/ + + To build extensions using other tool chains, see the "Using + non-Microsoft compilers on Windows" section in the distutils handbook: + + http://www.python.org/doc/current/inst/non-ms-compilers.html + + For additional information on how to build extensions using the + popular MinGW compiler, see: + + http://mingw.org (compiler) + http://sebsauvage.net/python/mingw.html (build instructions) + http://sourceforge.net/projects/gnuwin32 (prebuilt libraries) diff --git a/docs/porting-pil-to-pillow.rst b/docs/porting-pil-to-pillow.rst new file mode 100644 index 000000000..93bc672af --- /dev/null +++ b/docs/porting-pil-to-pillow.rst @@ -0,0 +1,17 @@ +Porting existing PIL-based code to Pillow +========================================= + +Pillow is a functional drop-in replacement for the Python Imaging Library. To +run your existing PIL-compatible code with Pillow, it needs to be modified to +import the ``Imaging`` module from the ``PIL`` namespace *instead* of the +global namespace. Change this:: + + import Image + +to this:: + + from PIL import Image + +The :py:mod:`_imaging` module has been moved. You can now import it like this:: + + from PIL.Image import core as _imaging diff --git a/docs/requirements.txt b/docs/requirements.txt index af38b4b69..d825a5fcc 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,7 +1,7 @@ # requirements for working on docs # install pillow from master if you're into that, but RtD needs this -pillow>=2.2.0 +pillow>=2.2.1 Jinja2==2.7.1 MarkupSafe==0.18