diff options
Diffstat (limited to 'external_libs/python/lockfile-0.10.2/doc')
3 files changed, 0 insertions, 527 deletions
diff --git a/external_libs/python/lockfile-0.10.2/doc/source/Makefile b/external_libs/python/lockfile-0.10.2/doc/source/Makefile deleted file mode 100644 index 1b1e8d28..00000000 --- a/external_libs/python/lockfile-0.10.2/doc/source/Makefile +++ /dev/null @@ -1,73 +0,0 @@ -# Makefile for Sphinx documentation -# - -# You can set these variables from the command line. -SPHINXOPTS = -SPHINXBUILD = sphinx-build -PAPER = - -# Internal variables. -PAPEROPT_a4 = -D latex_paper_size=a4 -PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d .build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . - -.PHONY: help clean html web pickle htmlhelp latex changes linkcheck - -help: - @echo "Please use \`make <target>' where <target> is one of" - @echo " html to make standalone HTML files" - @echo " pickle to make pickle files (usable by e.g. sphinx-web)" - @echo " htmlhelp to make HTML files and a HTML help project" - @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" - @echo " changes to make an overview over all changed/added/deprecated items" - @echo " linkcheck to check all external links for integrity" - -clean: - -rm -rf .build/* - -html: - mkdir -p .build/html .build/doctrees - $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) .build/html - @echo - @echo "Build finished. The HTML pages are in .build/html." - -pickle: - mkdir -p .build/pickle .build/doctrees - $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) .build/pickle - @echo - @echo "Build finished; now you can process the pickle files or run" - @echo " sphinx-web .build/pickle" - @echo "to start the sphinx-web server." - -web: pickle - -htmlhelp: - mkdir -p .build/htmlhelp .build/doctrees - $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) .build/htmlhelp - @echo - @echo "Build finished; now you can run HTML Help Workshop with the" \ - ".hhp project file in .build/htmlhelp." - -latex: - mkdir -p .build/latex .build/doctrees - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) .build/latex - @echo - @echo "Build finished; the LaTeX files are in .build/latex." - @echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \ - "run these through (pdf)latex." - -changes: - mkdir -p .build/changes .build/doctrees - $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) .build/changes - @echo - @echo "The overview file is in .build/changes." - -linkcheck: - mkdir -p .build/linkcheck .build/doctrees - $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) .build/linkcheck - @echo - @echo "Link check complete; look for any errors in the above output " \ - "or in .build/linkcheck/output.txt." - -html.zip: html - (cd .build/html ; zip -r ../../$@ *) diff --git a/external_libs/python/lockfile-0.10.2/doc/source/conf.py b/external_libs/python/lockfile-0.10.2/doc/source/conf.py deleted file mode 100644 index 623edcb5..00000000 --- a/external_libs/python/lockfile-0.10.2/doc/source/conf.py +++ /dev/null @@ -1,179 +0,0 @@ -# -*- coding: utf-8 -*- -# -# lockfile documentation build configuration file, created by -# sphinx-quickstart on Sat Sep 13 17:54:17 2008. -# -# This file is execfile()d with the current directory set to its containing dir. -# -# The contents of this file are pickled, so don't put values in the namespace -# that aren't pickleable (module imports are okay, they're removed automatically). -# -# All configuration values have a default value; values that are commented out -# serve to show the default value. - -import sys, os - -# If your extensions are in another directory, add it here. If the directory -# is relative to the documentation root, use os.path.abspath to make it -# absolute, like shown here. -#sys.path.append(os.path.abspath('some/directory')) - -# General configuration -# --------------------- - -# Add any Sphinx extension module names here, as strings. They can be extensions -# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = [] - -# Add any paths that contain templates here, relative to this directory. -templates_path = ['.templates'] - -# The suffix of source filenames. -source_suffix = '.rst' - -# The master toctree document. -master_doc = 'index' - -# General substitutions. -project = 'lockfile' -copyright = '2008, Skip Montanaro' - -# The default replacements for |version| and |release|, also used in various -# other places throughout the built documents. -# -# The short X.Y version. -version = '0.3' -# The full version, including alpha/beta/rc tags. -release = '0.3' - -# 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 documents that shouldn't be included in the build. -#unused_docs = [] - -# List of directories, relative to source directories, that shouldn't be searched -# for source files. -#exclude_dirs = [] - -# 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' - - -# Options for HTML output -# ----------------------- - -# The style sheet to use for HTML and HTML Help pages. A file of that name -# must exist either in Sphinx' static/ path, or in one of the custom paths -# given in html_static_path. -html_style = 'default.css' - -# The name for this set of Sphinx documents. If None, it defaults to -# "<project> v<release> documentation". -#html_title = None - -# A shorter title for the navigation bar. Default is the same as html_title. -#html_short_title = None - -# The name of an image file (within the static path) to place at the top of -# the sidebar. -#html_logo = None - -# The name of an image file (within the static path) to use as favicon of the -# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 -# pixels large. -#html_favicon = None - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -#html_static_path = ['.static'] - -# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, -# using the given strftime format. -html_last_updated_fmt = '%b %d, %Y' - -# If true, SmartyPants will be used to convert quotes and dashes to -# typographically correct entities. -#html_use_smartypants = True - -# Custom sidebar templates, maps document names to template names. -#html_sidebars = {} - -# Additional templates that should be rendered to pages, maps page names to -# template names. -#html_additional_pages = {} - -# If false, no module index is generated. -#html_use_modindex = True - -# If false, no index is generated. -#html_use_index = True - -# If true, the index is split into individual pages for each letter. -#html_split_index = False - -# If true, the reST sources are included in the HTML build as _sources/<name>. -#html_copy_source = True - -# If true, an OpenSearch description file will be output, and all pages will -# contain a <link> tag referring to it. The value of this option must be the -# base URL from which the finished HTML is served. -#html_use_opensearch = '' - -# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml"). -#html_file_suffix = '' - -# Output file base name for HTML help builder. -htmlhelp_basename = 'lockfiledoc' - - -# Options for LaTeX output -# ------------------------ - -# The paper size ('letter' or 'a4'). -#latex_paper_size = 'letter' - -# The font size ('10pt', '11pt' or '12pt'). -#latex_font_size = '10pt' - -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, author, document class [howto/manual]). -latex_documents = [ - ('lockfile', 'lockfile.tex', 'lockfile Documentation', - 'Skip Montanaro', '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 - -# Additional stuff for the LaTeX preamble. -#latex_preamble = '' - -# Documents to append as an appendix to all manuals. -#latex_appendices = [] - -# If false, no module index is generated. -#latex_use_modindex = True diff --git a/external_libs/python/lockfile-0.10.2/doc/source/index.rst b/external_libs/python/lockfile-0.10.2/doc/source/index.rst deleted file mode 100644 index f76173dc..00000000 --- a/external_libs/python/lockfile-0.10.2/doc/source/index.rst +++ /dev/null @@ -1,275 +0,0 @@ - -:mod:`lockfile` --- Platform-independent file locking -===================================================== - -.. module:: lockfile - :synopsis: Platform-independent file locking -.. moduleauthor:: Skip Montanaro <skip@pobox.com> -.. sectionauthor:: Skip Montanaro <skip@pobox.com> - - -.. note:: - - This package is pre-release software. Between versions 0.8 and 0.9 it - was changed from a module to a package. It is quite possible that the - API and implementation will change again in important ways as people test - it and provide feedback and bug fixes. In particular, if the mkdir-based - locking scheme is sufficient for both Windows and Unix platforms, the - link-based scheme may be deleted so that only a single locking scheme is - used, providing cross-platform lockfile cooperation. - -.. note:: - - The implementation uses the `with` statement, both in the tests and in the - main code, so will only work out-of-the-box with Python 2.5 or later. - However, the use of the `with` statement is minimal, so if you apply the - patch in the included 2.4.diff file you can use it with Python 2.4. It's - possible that it will work in Python 2.3 with that patch applied as well, - though the doctest code relies on APIs new in 2.4, so will have to be - rewritten somewhat to allow testing on 2.3. As they say, patches welcome. - ``;-)`` - -The :mod:`lockfile` package exports a :class:`LockFile` class which provides -a simple API for locking files. Unlike the Windows :func:`msvcrt.locking` -function, the Unix :func:`fcntl.flock`, :func:`fcntl.lockf` and the -deprecated :mod:`posixfile` module, the API is identical across both Unix -(including Linux and Mac) and Windows platforms. The lock mechanism relies -on the atomic nature of the :func:`link` (on Unix) and :func:`mkdir` (On -Windows) system calls. It also contains several lock-method-specific -modules: :mod:`lockfile.linklockfile`, :mod:`lockfile.mkdirlockfile`, and -:mod:`lockfile.sqlitelockfile`, each one exporting a single class. For -backwards compatibility with versions before 0.9 the :class:`LinkFileLock`, -:class:`MkdirFileLock` and :class:`SQLiteFileLock` objects are exposed as -attributes of the top-level lockfile package, though this use was deprecated -starting with version 0.9 and will be removed in version 1.0. - -.. note:: - - The current implementation uses :func:`os.link` on Unix, but since that - function is unavailable on Windows it uses :func:`os.mkdir` there. At - this point it's not clear that using the :func:`os.mkdir` method would be - insufficient on Unix systems. If it proves to be adequate on Unix then - the implementation could be simplified and truly cross-platform locking - would be possible. - -.. note:: - - The current implementation doesn't provide for shared vs. exclusive - locks. It should be possible for multiple reader processes to hold the - lock at the same time. - -The module defines the following exceptions: - -.. exception:: Error - - This is the base class for all exceptions raised by the :class:`LockFile` - class. - -.. exception:: LockError - - This is the base class for all exceptions raised when attempting to lock - a file. - -.. exception:: UnlockError - - This is the base class for all exceptions raised when attempting to - unlock a file. - -.. exception:: LockTimeout - - This exception is raised if the :func:`LockFile.acquire` method is - called with a timeout which expires before an existing lock is released. - -.. exception:: AlreadyLocked - - This exception is raised if the :func:`LockFile.acquire` detects a - file is already locked when in non-blocking mode. - -.. exception:: LockFailed - - This exception is raised if the :func:`LockFile.acquire` detects some - other condition (such as a non-writable directory) which prevents it from - creating its lock file. - -.. exception:: NotLocked - - This exception is raised if the file is not locked when - :func:`LockFile.release` is called. - -.. exception:: NotMyLock - - This exception is raised if the file is locked by another thread or - process when :func:`LockFile.release` is called. - -The following classes are provided: - -.. class:: linklockfile.LinkLockFile(path, threaded=True) - - This class uses the :func:`link(2)` system call as the basic lock - mechanism. *path* is an object in the file system to be locked. It need - not exist, but its directory must exist and be writable at the time the - :func:`acquire` and :func:`release` methods are called. *threaded* is - optional, but when set to :const:`True` locks will be distinguished - between threads in the same process. - -.. class:: symlinklockfile.SymlinkLockFile(path, threaded=True) - - This class uses the :func:`symlink(2)` system call as the basic lock - mechanism. The parameters have the same meaning and constraints as for - the :class:`LinkLockFile` class. - -.. class:: mkdirlockfile.MkdirLockFile(path, threaded=True) - - This class uses the :func:`mkdir(2)` system call as the basic lock - mechanism. The parameters have the same meaning and constraints as for - the :class:`LinkLockFile` class. - -.. class:: sqlitelockfile.SQLiteLockFile(path, threaded=True) - - This class uses the :mod:`sqlite3` module to implement the lock - mechanism. The parameters have the same meaning as for the - :class:`LinkLockFile` class. - -.. class:: LockBase(path, threaded=True) - - This is the base class for all concrete implementations and is available - at the lockfile package level so programmers can implement other locking - schemes. - -.. function:: locked(path, timeout=None) - - This function provides a decorator which insures the decorated function - is always called with the lock held. - -By default, the :const:`LockFile` object refers to the -:class:`mkdirlockfile.MkdirLockFile` class on Windows. On all other -platforms it refers to the :class:`linklockfile.LinkLockFile` class. - -When locking a file the :class:`linklockfile.LinkLockFile` class creates a -uniquely named hard link to an empty lock file. That hard link contains the -hostname, process id, and if locks between threads are distinguished, the -thread identifier. For example, if you want to lock access to a file named -"README", the lock file is named "README.lock". With per-thread locks -enabled the hard link is named HOSTNAME-THREADID-PID. With only per-process -locks enabled the hard link is named HOSTNAME--PID. - -When using the :class:`mkdirlockfile.MkdirLockFile` class the lock file is a -directory. Referring to the example above, README.lock will be a directory -and HOSTNAME-THREADID-PID will be an empty file within that directory. - -.. seealso:: - - Module :mod:`msvcrt` - Provides the :func:`locking` function, the standard Windows way of - locking (parts of) a file. - - Module :mod:`posixfile` - The deprecated (since Python 1.5) way of locking files on Posix systems. - - Module :mod:`fcntl` - Provides the current best way to lock files on Unix systems - (:func:`lockf` and :func:`flock`). - -LockFile Objects ----------------- - -:class:`LockFile` objects support the `context manager` protocol used by the -statement:`with` statement. The timeout option is not supported when used in -this fashion. While support for timeouts could be implemented, there is no -support for handling the eventual :exc:`Timeout` exceptions raised by the -:func:`__enter__` method, so you would have to protect the `with` statement with -a `try` statement. The resulting construct would not be any simpler than just -using a `try` statement in the first place. - -:class:`LockFile` has the following user-visible methods: - -.. method:: LockFile.acquire(timeout=None) - - Lock the file associated with the :class:`LockFile` object. If the - *timeout* is omitted or :const:`None` the caller will block until the - file is unlocked by the object currently holding the lock. If the - *timeout* is zero or a negative number the :exc:`AlreadyLocked` exception - will be raised if the file is currently locked by another process or - thread. If the *timeout* is positive, the caller will block for that - many seconds waiting for the lock to be released. If the lock is not - released within that period the :exc:`LockTimeout` exception will be - raised. - -.. method:: LockFile.release() - - Unlock the file associated with the :class:`LockFile` object. If the - file is not currently locked, the :exc:`NotLocked` exception is raised. - If the file is locked by another thread or process the :exc:`NotMyLock` - exception is raised. - -.. method:: is_locked() - - Return the status of the lock on the current file. If any process or - thread (including the current one) is locking the file, :const:`True` is - returned, otherwise :const:`False` is returned. - -.. method:: break_lock() - - If the file is currently locked, break it. - -.. method:: i_am_locking() - - Returns true if the caller holds the lock. - -Examples --------- - -This example is the "hello world" for the :mod:`lockfile` package:: - - from lockfile import LockFile - lock = LockFile("/some/file/or/other") - with lock: - print lock.path, 'is locked.' - -To use this with Python 2.4, you can execute:: - - from lockfile import LockFile - lock = LockFile("/some/file/or/other") - lock.acquire() - print lock.path, 'is locked.' - lock.release() - -If you don't want to wait forever, you might try:: - - from lockfile import LockFile - lock = LockFile("/some/file/or/other") - while not lock.i_am_locking(): - try: - lock.acquire(timeout=60) # wait up to 60 seconds - except LockTimeout: - lock.break_lock() - lock.acquire() - print "I locked", lock.path - lock.release() - -You can also insure that a lock is always held when appropriately decorated -functions are called:: - - from lockfile import locked - @locked("/tmp/mylock") - def func(a, b): - return a + b - -Other Libraries ---------------- - -The idea of implementing advisory locking with a standard API is not new -with :mod:`lockfile`. There are a number of other libraries available: - -* locknix - http://pypi.python.org/pypi/locknix - Unix only -* mx.MiscLockFile - from Marc André Lemburg, part of the mx.Base - distribution - cross-platform. -* Twisted - http://twistedmatrix.com/trac/browser/trunk/twisted/python/lockfile.py -* zc.lockfile - http://pypi.python.org/pypi/zc.lockfile - - -Contacting the Author ---------------------- - -If you encounter any problems with ``lockfile``, would like help or want to -submit a patch, check http://launchpad.net/pylockfile |