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
|
#! /usr/bin/python
|
||||||
|
# -*- coding: utf8 -*-
|
||||||
|
|
||||||
from __future__ import absolute_import, division, print_function
|
from __future__ import absolute_import, division, print_function
|
||||||
|
|
||||||
|
@ -11,7 +12,14 @@ from .utils import logger, logdir, statfiles
|
||||||
|
|
||||||
|
|
||||||
class OutputNamingConvention(object):
|
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',
|
expected = ['name_txt', 'name_pdf', 'name_htmls', 'name_html',
|
||||||
'name_indexhtml']
|
'name_indexhtml']
|
||||||
|
|
||||||
|
@ -43,13 +51,40 @@ class OutputNamingConvention(object):
|
||||||
def name_indexhtml(self):
|
def name_indexhtml(self):
|
||||||
return os.path.join(self.dirname, 'index.html')
|
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):
|
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):
|
def __repr__(self):
|
||||||
return '<%s:%s>' % (self.__class__.__name__, self.dirname)
|
return '<%s:%s>' % (self.__class__.__name__, self.dirname)
|
||||||
|
|
||||||
def __init__(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.dirname = os.path.abspath(dirname)
|
||||||
self.stem = os.path.basename(self.dirname)
|
self.stem = os.path.basename(self.dirname)
|
||||||
parent = os.path.dirname(self.dirname)
|
parent = os.path.dirname(self.dirname)
|
||||||
|
@ -61,16 +96,12 @@ class OutputDirectory(OutputNamingConvention):
|
||||||
self.logdir = os.path.join(self.dirname, logdir)
|
self.logdir = os.path.join(self.dirname, logdir)
|
||||||
super(OutputDirectory, self).__init__(self.dirname, self.stem)
|
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):
|
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)
|
logger.info("%s cleaning dir %s.", self.stem, self.dirname)
|
||||||
if os.path.isdir(self.dirname):
|
if os.path.isdir(self.dirname):
|
||||||
shutil.rmtree(self.dirname)
|
shutil.rmtree(self.dirname)
|
||||||
|
@ -94,22 +125,56 @@ class OutputDirectory(OutputNamingConvention):
|
||||||
|
|
||||||
|
|
||||||
class OutputCollection(collections.MutableMapping):
|
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):
|
def __repr__(self):
|
||||||
return '<%s:(%s docs)>' % (self.__class__.__name__, len(self))
|
return '<%s:(%s docs)>' % (self.__class__.__name__, len(self))
|
||||||
|
|
||||||
def __init__(self, dirname=None):
|
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:
|
if dirname is None:
|
||||||
return
|
return
|
||||||
elif not os.path.isdir(dirname):
|
elif not os.path.isdir(dirname):
|
||||||
logger.critical("Output collection dir %s must already exist.",
|
logger.critical("Output collection dir %s must already exist.",
|
||||||
dirname)
|
dirname)
|
||||||
raise IOError(errno.ENOENT, os.strerror(errno.ENOENT), 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)
|
name = os.path.join(dirname, fname)
|
||||||
if not os.path.isdir(name):
|
if not os.path.isdir(name):
|
||||||
logger.info("Skipping non-directory %s (in %s)", name, dirname)
|
logger.info("Skipping non-directory %s (in %s)", name, dirname)
|
||||||
continue
|
continue
|
||||||
|
logger.debug("Found directory %s (in %s)", name, dirname)
|
||||||
o = OutputDirectory(name)
|
o = OutputDirectory(name)
|
||||||
assert o.stem not in self
|
assert o.stem not in self
|
||||||
self[o.stem] = o
|
self[o.stem] = o
|
||||||
|
|
Loading…
Reference in New Issue