mirror of https://github.com/tLDP/python-tldp
adding basic docstrings
This commit is contained in:
parent
605b57a1ea
commit
bf768d0277
|
@ -1,4 +1,5 @@
|
|||
#! /usr/bin/python
|
||||
# -*- coding: utf8 -*-
|
||||
|
||||
from __future__ import absolute_import, division, print_function
|
||||
|
||||
|
@ -11,7 +12,14 @@ from .utils import logger, logdir, statfiles
|
|||
|
||||
|
||||
class OutputNamingConvention(object):
|
||||
'''A base class inherited by OutputDirectory to ensure consistent
|
||||
naming of files across the output collection of documents,
|
||||
regardless of the source document type and processing toolchain
|
||||
choice.
|
||||
|
||||
Sets a list of names for documents that are expected to be present
|
||||
in order to report that the directory iscomplete.
|
||||
'''
|
||||
expected = ['name_txt', 'name_pdf', 'name_htmls', 'name_html',
|
||||
'name_indexhtml']
|
||||
|
||||
|
@ -43,13 +51,40 @@ class OutputNamingConvention(object):
|
|||
def name_indexhtml(self):
|
||||
return os.path.join(self.dirname, 'index.html')
|
||||
|
||||
@property
|
||||
def iscomplete(self):
|
||||
'''True if the output directory contains all expected documents'''
|
||||
present = list()
|
||||
for prop in self.expected:
|
||||
name = getattr(self, prop, None)
|
||||
assert name is not None
|
||||
present.append(os.path.isfile(name))
|
||||
return all(present)
|
||||
|
||||
|
||||
class OutputDirectory(OutputNamingConvention):
|
||||
'''A class providing a container for each set of output documents
|
||||
for a given source document and general methods for operating on
|
||||
and preparing the output directory for a document processor.
|
||||
For example, the process of generating each document type for a single
|
||||
source (e.g. 'Unicode-HOWTO') would be managed by this object.
|
||||
|
||||
An important element of the OutputDirectory is the stem, determined
|
||||
from the directory name when __init__() is called.
|
||||
'''
|
||||
def __repr__(self):
|
||||
return '<%s:%s>' % (self.__class__.__name__, self.dirname)
|
||||
|
||||
def __init__(self, dirname):
|
||||
'''constructor
|
||||
:param dirname: directory name for all output documents
|
||||
|
||||
This directory name is expected to end with the document stem name,
|
||||
for example '/path/to/the/collection/Unicode-HOWTO'. The parent
|
||||
directory (e.g. '/path/to/the/collection' must exist already. The
|
||||
output directory itself will be created, or emptied and cleared if
|
||||
the document needs to be rebuilt.
|
||||
'''
|
||||
self.dirname = os.path.abspath(dirname)
|
||||
self.stem = os.path.basename(self.dirname)
|
||||
parent = os.path.dirname(self.dirname)
|
||||
|
@ -61,16 +96,12 @@ class OutputDirectory(OutputNamingConvention):
|
|||
self.logdir = os.path.join(self.dirname, logdir)
|
||||
super(OutputDirectory, self).__init__(self.dirname, self.stem)
|
||||
|
||||
@property
|
||||
def iscomplete(self):
|
||||
present = list()
|
||||
for prop in self.expected:
|
||||
name = getattr(self, prop, None)
|
||||
assert name is not None
|
||||
present.append(os.path.isfile(name))
|
||||
return all(present)
|
||||
|
||||
def clean(self):
|
||||
'''remove the output directory for this document
|
||||
|
||||
This is done as a matter of course when the output documents must be
|
||||
regenerated. Better to start fresh.
|
||||
'''
|
||||
logger.info("%s cleaning dir %s.", self.stem, self.dirname)
|
||||
if os.path.isdir(self.dirname):
|
||||
shutil.rmtree(self.dirname)
|
||||
|
@ -94,22 +125,56 @@ class OutputDirectory(OutputNamingConvention):
|
|||
|
||||
|
||||
class OutputCollection(collections.MutableMapping):
|
||||
'''a dict-like container for OutputDirectory objects
|
||||
|
||||
The key of an OutputCollection is the stem name of the document, which
|
||||
allows convenient access and guaranteed non-collision.
|
||||
'''
|
||||
def __repr__(self):
|
||||
return '<%s:(%s docs)>' % (self.__class__.__name__, len(self))
|
||||
|
||||
def __init__(self, dirname=None):
|
||||
'''construct an OutputCollection
|
||||
|
||||
if dirname is not supplied, OutputCollection is basically, a dict().
|
||||
if dirname is supplied, then OutputCollection scans the filesystem
|
||||
for subdirectories of dirname and creates an OutputDirectory for each
|
||||
subdir. Each subdir name is used as the stem (or key) for holding the
|
||||
OutputDirectory in the OutputCollection.
|
||||
|
||||
For example, consider the following directory tree:
|
||||
|
||||
en
|
||||
├── Latvian-HOWTO
|
||||
├── Scanner-HOWTO
|
||||
├── UUCP-HOWTO
|
||||
└── Wireless-HOWTO
|
||||
|
||||
If called like OutputCollection("en"), the result in memory would be
|
||||
a structure resembling this:
|
||||
|
||||
OutputCollection("/path/en") = {
|
||||
"Latvian-HOWTO": OutputDirectory("/path/en/Latvian-HOWTO")
|
||||
"Scanner-HOWTO": OutputDirectory("/path/en/Scanner-HOWTO")
|
||||
"UUCP-HOWTO": OutputDirectory("/path/en/UUCP-HOWTO")
|
||||
"Wireless-HOWTO": OutputDirectory("/path/en/Wireless-HOWTO")
|
||||
}
|
||||
|
||||
The use of the stem as a key works conveniently with the
|
||||
SourceCollection which uses the same strategy on SourceDocuments.
|
||||
'''
|
||||
if dirname is None:
|
||||
return
|
||||
elif not os.path.isdir(dirname):
|
||||
logger.critical("Output collection dir %s must already exist.",
|
||||
dirname)
|
||||
raise IOError(errno.ENOENT, os.strerror(errno.ENOENT), dirname)
|
||||
for fname in os.listdir(dirname):
|
||||
for fname in sorted(os.listdir(dirname)):
|
||||
name = os.path.join(dirname, fname)
|
||||
if not os.path.isdir(name):
|
||||
logger.info("Skipping non-directory %s (in %s)", name, dirname)
|
||||
continue
|
||||
logger.debug("Found directory %s (in %s)", name, dirname)
|
||||
o = OutputDirectory(name)
|
||||
assert o.stem not in self
|
||||
self[o.stem] = o
|
||||
|
|
Loading…
Reference in New Issue