Embedding PyScaffoldΒΆ
PyScaffold is expected to be used from terminal, via putup
command line
application. It is, however, possible to write an external script or program
that embeds PyScaffold and use it to perform some custom actions.
The public Python API for embedding PyScaffold is composed by the main function
pyscaffold.api.create_project
in addition to pyscaffold.api.NO_CONFIG
,
pyscaffold.log.DEFAULT_LOGGER
, pyscaffold.log.logger
(partially,
see details bellow), and the constructors for the extension classes belonging
to the pyscaffold.extenstions
module (the other methods and functions
are not considered part of the API). This API, as explicitly listed, follows
semantic versioning and will not change in a backwards incompatible way
between releases. The remaining methods and functions are not guaranteed to be stable.
The following example illustrates a typical embedded usage of PyScaffold:
import logging
from pyscaffold.api import create_project
from pyscaffold.extenstions.cirrus import Cirrus
from pyscaffold.extenstions.namespace import Namespace
from pyscaffold.log import DEFAULT_LOGGER as LOGGER_NAME
logging.getLogger(LOGGER_NAME).setLevel(logging.INFO)
create_project(
project_path="my-proj-name",
author="Your Name",
namespace="some.namespace",
license="MIT",
extensions=[Cirrus(), Namespace()],
)
Note that no built-in extension (e.g. cirrus and namespace)
is activated by default. The extensions
option should be manually
populated when convenient.
PyScaffold uses the logging infrastructure from Python standard library, and
emits notifications during its execution. Therefore, it is possible to control
which messages are logged by properly setting the log level (internally, most
of the messages are produced under the INFO
level). By default, a
StreamHandler
is attached to the logger, however it is
possible to replace it with a custom handler using
logging.Logger.removeHandler
and logging.Logger.addHandler
. The
logger object is available under the logger
variable of
the pyscaffold.log
module. The default handler is available under the
handler
property of the
logger
object.