dk-tasklib 3.0.9__py3-none-any.whl

dktasklib/entry_points/confbase.py

@@ -0,0 +1,172 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file does only contain a selection of the most common options. For a
+# full list see the documentation:
+# http://www.sphinx-doc.org/en/stable/config
+
+# -- Path setup --------------------------------------------------------------
+
+# 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.
+#
+import os
+import sys
+sys.path.insert(0, os.path.abspath('..'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = '##{PACKAGE}'
+copyright = '##{YEAR}, ##{AUTHOR}'
+author = '##{AUTHOR}'
+
+# The short X.Y version
+version = '##{VERSION}'
+# The full version, including alpha/beta/rc tags
+release = '##{VERSION}'
+
+
+# -- General configuration ---------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#
+# 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.intersphinx',
+    'sphinx.ext.todo',
+    'sphinx.ext.viewcode',
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+# source_suffix = ['.rst', '.md']
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'index'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = 'en'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path .
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'alabaster'
+
+# 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 = {}
+
+# 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']
+
+# Custom sidebar templates, must be a dictionary that maps document names
+# to template names.
+#
+# The default sidebars (for documents that don't match any pattern) are
+# defined by theme itself.  Builtin themes are using these templates by
+# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
+# 'searchbox.html']``.
+#
+# html_sidebars = {}
+
+
+# -- Options for HTMLHelp output ---------------------------------------------
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = '##{PACKAGE}doc'
+
+
+# -- Options for LaTeX output ------------------------------------------------
+
+latex_elements = {
+    # The paper size ('letterpaper' or 'a4paper').
+    #
+    # 'papersize': 'letterpaper',
+
+    # The font size ('10pt', '11pt' or '12pt').
+    #
+    # 'pointsize': '10pt',
+
+    # Additional stuff for the LaTeX preamble.
+    #
+    # 'preamble': '',
+
+    # Latex figure (float) alignment
+    #
+    # 'figure_align': 'htbp',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+    (master_doc, '##{PACKAGE}.tex', '##{PACKAGE} Documentation',
+     '##{AUTHOR}', 'manual'),
+]
+
+
+# -- Options for manual page output ------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    (master_doc, '##{PACKAGE}', '##{PACKAGE} Documentation',
+     [author], 1)
+]
+
+
+# -- 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 = [
+    (master_doc, '##{PACKAGE}', '##{PACKAGE} Documentation',
+     author, '##{PACKAGE}', 'One line description of project.',
+     'Miscellaneous'),
+]
+
+
+# -- Extension configuration -------------------------------------------------
+
+# -- Options for intersphinx extension ---------------------------------------
+
+# Example configuration for intersphinx: refer to the Python standard library.
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3', None),
+}
+
+# -- Options for todo extension ----------------------------------------------
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = True

dktasklib/entry_points/dktasklibcmd.py

@@ -0,0 +1,102 @@
+"""Commands installed by setup.py
+"""
+# pragma: nocover
+import argparse
+import datetime
+import os
+import sys
+
+import textwrap
+
+from dkfileutils.path import Path
+from .._version import __version__
+from .pytemplate import PyTemplate
+from ..runners import run
+
+DIRNAME = Path(os.path.dirname(__file__))
+
+
+def install_cmd(args):
+    """Install a basic task.py to the current directory.
+    """
+    cwd = Path.curdir()
+    tasks_file = cwd / 'tasks.py'
+    if tasks_file.exists() and not args.force:
+        print("tasks.py exists (use --force to overwrite)")
+        sys.exit(1)
+    taskbase = DIRNAME / 'taskbase.py'
+    txt = taskbase.read('rb')
+    txt = txt.replace(b'\r\n', b'\n')
+    t = PyTemplate(txt)
+    tasks_file.write(t.substitute(
+        VERSION=__version__
+    ))
+    if args.django:
+        add_django_to_docs_conf()
+
+
+def create_docs_cmd(args):
+    cwd = Path.curdir()
+    docsdir = cwd / 'docs'
+    if docsdir.exists() and not args.force:
+        print("docs directory exists (use --force to overwrite)")
+        sys.exit(1)
+    confbase = DIRNAME / 'confbase.py'
+    txt = confbase.read('rb')
+    txt = txt.replace(b'\r\n', b'\n')
+    t = PyTemplate(txt)
+
+    docsdir.makedirs()
+    (docsdir / 'conf.py').write(t.substitute(
+        VERSION=run('python setup.py --version'),
+        PACKAGE=run('python setup.py --name'),
+        YEAR=datetime.date.today().year,
+        AUTHOR=run('python setup.py --author').strip()
+    ))
+
+
+def add_django_to_docs_conf():
+    cwd = Path.curdir()
+    conf_file = cwd / 'docs' / 'conf.py'
+    if 'django.setup()' in conf_file.read():
+        print("./docs/conf.py already contains django.setup()")
+        return
+
+    src = conf_file.read('r')
+    pre, post = src.split('\n\n', 1)
+    conf_file.write(
+        pre + "\n\n" +
+        textwrap.dedent("""\
+        import django
+        django.setup()
+        """) + "\n\n" +
+        post
+    )
+
+
+def main(args=None):
+    args = args or sys.argv[1:]
+    p = argparse.ArgumentParser()
+    commands = list(sorted([name[:-4] for name in globals()
+                            if name.endswith('_cmd')]))
+
+    p.add_argument('command', help="run command (available commands: %s)" % ', '.join(commands))
+    p.add_argument('--version', action='version', version='%(prog)s ' + __version__)
+    p.add_argument('--verbose', '-v', action='store_true', help="verbose output")
+    p.add_argument('--force', '-f', action='store_true', help="force execution of commands.")
+    p.add_argument('--django', '-d', action='store_true', help="make django specific changes.")
+
+    args = p.parse_args(args)
+
+    if args.verbose:
+        print("ARGS:", args)
+
+    if args.command not in commands:
+        print("Unknown command:", args.command)
+        sys.exit(1)
+
+    globals()[args.command + '_cmd'](args)
+
+
+if __name__ == "__main__":
+    main()

dktasklib/entry_points/pytemplate.py

@@ -0,0 +1,16 @@
+from string import Template
+
+
+class PyTemplate(Template):
+    """
+    Template strings that can replace ##{PATTERN} instances.
+    """
+    def __init__(self, t):
+        if isinstance(t, bytes):
+            t = t.decode('u8')
+        super().__init__(t.replace('$', '$$').replace('##{', '${'))
+
+    def substitute(self, *args, **kw):
+        return super().substitute(
+            **{k.upper(): v for k, v in kw.items()}
+        )

dktasklib/entry_points/taskbase.py

@@ -0,0 +1,135 @@
+"""
+Base version of package/tasks.py, created by version ##{VERSION} of
+
+    package/root/dir> dk-tasklib install
+
+(it should reside in the root directory of your package)
+
+This file defines tasks for the Invoke tool: http://www.pyinvoke.org
+
+Basic usage::
+
+    inv -l               # list all available tasks
+    inv build -f         # build everything, forcefully
+    inv build --docs     # only build the docs
+
+dk-tasklib is a library of basic tasks that tries to automate common tasks.
+dk-tasklib will attempt to install any tools/libraries/etc. that are required,
+e.g. when running the task to compile x.less to x.css, it will check that
+the lessc compiler is installed (and if not it will attempt to install it).
+
+This file is an initial skeleton, you are supposed to edit and add to it so it
+will fit your use case.
+
+
+"""
+# pragma: nocover
+import os
+import warnings
+
+from dkfileutils.changed import changed
+from dkfileutils.path import Path
+from dktasklib.wintask import task
+from invoke import Collection
+
+from dktasklib import docs as doctools
+from dktasklib import lessc
+from dktasklib import version, upversion
+from dktasklib.manage import collectstatic
+from dktasklib.package import Package, package
+from dktasklib.watch import Watcher
+# from dktasklib.publish import publish
+
+#: where tasks.py is located (root of package)
+DIRNAME = Path(os.path.dirname(__file__))
+
+# collectstatic
+# --------------
+# Specify which settings file should be used when running
+# `python manage.py collectstatic` (must be on the path or package root
+# directory).
+DJANGO_SETTINGS_MODULE = ''
+
+# .less
+# ------
+# there should be a mypkg/mypkg/less/mypkg.less file that imports any other
+# needed sources
+
+# ============================================================================
+# autodoc is in a separate process, so can't use settings.configure().
+HAVE_SETTINGS = bool(DJANGO_SETTINGS_MODULE)
+if not HAVE_SETTINGS and (DIRNAME / 'settings.py').exists():
+    # look for a dummy settings.py module in the root of the package.
+    DJANGO_SETTINGS_MODULE = 'settings'
+if DJANGO_SETTINGS_MODULE:
+    os.environ['DJANGO_SETTINGS_MODULE'] = DJANGO_SETTINGS_MODULE
+WARN_ABOUT_SETTINGS = not bool(DJANGO_SETTINGS_MODULE)
+
+
+@task
+def build(ctx, less=False, docs=False, force=False):
+    """Build everything and collectstatic.
+    """
+    specified = any([less, docs])
+    buildall = not specified
+
+    if buildall or less:
+        less_fname = ctx.pkg.source_less / ctx.pkg.name + '.less'
+        if less_fname.exists():
+            lessc.LessRule(
+                ctx,
+                src='{pkg.source_less}/{pkg.name}.less',
+                dst='{pkg.django_static}/{pkg.name}/css/{pkg.name}-{version}.min.css',
+                force=force
+            )
+        elif less:
+            warnings.warn(
+                "WARNING: build --less specified, but no file at: " + less_fname
+            )
+
+    if buildall or docs:
+        if WARN_ABOUT_SETTINGS:
+            warnings.warn(
+                "autodoc might need a dummy settings file in the root of "
+                "your package. Since it runs in a separate process you cannot"
+                "use settings.configure()"
+            )
+        doctools.build(ctx, force=force)
+
+    if HAVE_SETTINGS and (force or changed(ctx.pkg.django_static)):
+        collectstatic(ctx, DJANGO_SETTINGS_MODULE, force=force)
+
+
+@task
+def watch(ctx):
+    """Automatically run build whenever a relevant file changes.
+    """
+    watcher = Watcher(ctx)
+    watcher.watch_directory(
+        path='{pkg.source_less}', ext='.less',
+        action=lambda e: build(ctx, less=True)
+    )
+    watcher.watch_directory(
+        path='{pkg.docs}', ext='.rst',
+        action=lambda e: build(ctx, docs=True)
+    )
+    watcher.start()
+
+
+# individual tasks that can be run from this project
+ns = Collection(
+    build,
+    watch,
+    lessc,
+    doctools,
+    version, upversion,
+    package,
+    collectstatic,
+    # publish,
+)
+ns.configure({
+    'pkg': Package(),
+    'run': {
+        'echo': True
+    }
+})

dktasklib/environment.py

@@ -0,0 +1,11 @@
+"""
+Global state.
+"""
+
+
+class Environment:
+    def __call__(self, ctx):
+        return ctx
+
+
+env = Environment()

dktasklib/executables.py

@@ -0,0 +1,200 @@
+import sys
+import warnings
+
+import invoke
+from dkfileutils.which import get_executable
+from dktasklib import Package
+from dktasklib.utils import win32
+from dktasklib import runners
+
+
+class MissingCommand(Exception):
+    """Exception thrown when a command (executable) is not found.
+    """
+    pass
+
+
+# noinspection PyShadowingNames
+class Executables:
+    """Class for finding executables on the host system.
+    """
+    def __init__(self):
+        self._cache = {}
+        self._ctx = None
+
+    @property
+    def ctx(self):
+        if self._ctx is None:
+            self._ctx = invoke.Context()
+        return self._ctx
+
+    def require(self, *dependencies):
+        """Ensure that all dependencies are available.
+           You should not need to call this yourself, use the :func:`requires`
+           decorator instead.
+        """
+        for dep in dependencies:
+            self.find(dep)
+
+    def find(self, name, requires=(), install_txt=''):
+        """Find the executable named ``name`` on the :envvar:`PATH`.
+
+           Args:
+               name (str):
+                    name of executable to find.
+               requires (List[str]):
+                    list of executables to find first.
+               install_txt (str):
+                    instructions for how to install the
+                    executable if it is not found.
+        """
+        if name not in self._cache:
+            self.require(*requires)
+
+            if hasattr(self, 'find_' + name):
+                self._cache[name] = getattr(self, 'find_' + name)()
+            else:
+                self._cache[name] = self._find_exe(name, requires, install_txt)
+        return self._cache[name]
+
+    def _find_exe(self, name, requires=(), install_txt=None):
+        fexe = get_executable(name)
+        if not fexe:  # pragma: nocover
+            # try $PKG/node_modules/.bin/<exe|cmd>
+            noderoot = Package().root / 'node_modules/.bin'
+            if name + '.cmd' in noderoot:
+                return str(noderoot / (name + '.cmd'))
+
+            if not install_txt:  # pragma: nocover
+                install_txt = "Missing command: %r" % name
+                if requires:
+                    install_txt += " [requires: %s]" % requires
+            raise MissingCommand(install_txt)
+        return fexe
+
+    def find_wheel(self):
+        exename = 'wheel'
+        exepath = get_executable(exename)
+        if not exepath:
+            pip = get_executable('pip')
+            cmd = pip + ' install wheel[signatures]'
+            if win32:
+                runners.run(cmd)
+                exepath = get_executable(exename)
+                # generate signing key if downloading wheel
+                runners.run(exepath + ' keygen')
+            else:
+                raise MissingCommand("Missing wheel (%s)" % cmd)
+            print('Your ~/.pypirc file should have a [pypi] section instead of a [server-login] section')
+        return exepath
+
+    def find_twine(self):
+        exename = 'twine'
+        exepath = get_executable(exename)
+        if not exepath:
+            pip = get_executable('pip')
+            cmd = pip + ' install twine'
+            if win32:
+                runners.run(cmd)
+                exepath = get_executable(exename)
+            else:
+                raise MissingCommand("Missing twine (%s)" % cmd)
+            print('Your ~/.pypirc file should have a [pypi] section instead of a [server-login] section')
+        return exepath
+
+    def find_uglify(self):
+        exename = 'uglifyjs'
+        exepath = get_executable(exename)
+        if not exepath:
+            npminstall = "npm install -g uglify-js --no-color"
+            if win32:
+                self.ctx.run(npminstall, echo=False, encoding="utf-8")
+                exepath = get_executable(exename)
+            else:
+                raise MissingCommand("Missing uglifyjs (%s)" % npminstall)
+        return exepath
+
+    def find_browserify(self):
+        exename = 'browserify'
+        exepath = get_executable(exename)
+        npminstall = "npm install -g browserify --no-color"
+        if not exepath:
+            if win32:
+                self.ctx.run(npminstall, echo=True, encoding="utf-8")
+                exepath = get_executable(exename)
+            else:
+                raise MissingCommand("Missing browserify (%s)" % npminstall)
+        return exepath
+
+    def find_babili(self):
+        exename = 'babili'
+        exepath = get_executable(exename)
+        npminstall = "npm install -g babili --no-color"
+        if not exepath:
+            if win32:
+                self.ctx.run(npminstall, echo=False, encoding="utf-8")
+                exepath = get_executable(exename)
+            else:
+                raise MissingCommand("Missing babili (%s)" % npminstall)
+        return exepath
+
+    def find_babel(self):
+        exename = 'babel'
+        exepath = get_executable(exename)
+        npminstall = "npm install -g babel-cli --no-color"
+        if not exepath:
+            if win32:
+                self.ctx.run(npminstall, echo=False, encoding="utf-8")
+                exepath = get_executable(exename)
+            else:
+                raise MissingCommand("Missing babel (%s)" % npminstall)
+        return exepath
+
+    def find_nodejs(self):  # pragma: nocover
+        """Find :program:`node`.
+        """
+        if sys.platform == 'win32':
+            node_exe = get_executable('node')
+        else:
+            node_exe = get_executable('nodejs') or get_executable('node')
+
+        if not node_exe:  # pragma: nocover
+            raise MissingCommand("""
+            Install Node.js using your OS package manager
+            https://github.com/joyent/node/wiki/Installing-Node.js-via-package-manager
+            """)
+        return node_exe
+
+    def find_npm(self):
+        """Find the node package manager (:program:`npm`).
+        """
+        npm_exe = get_executable('npm')
+        if not npm_exe:  # pragma: nocover
+            raise MissingCommand("""
+            Install Node.js using your OS package manager
+            https://github.com/joyent/node/wiki/Installing-Node.js-via-package-manager
+            """)
+        return npm_exe
+
+
+#: public interface to the :py:class:`Executables` class
+exe = Executables()
+
+
+def requires(*deps):
+    """Decorator to declare global dependencies/requirements.
+
+       Usage (``@task`` must be last)::
+
+           @requires('nodejs', 'npm', 'lessc')
+           @task
+           def mytask(..)
+
+    """
+    def _wrapper(fn):
+        try:
+            exe.require(*deps)
+        except MissingCommand as e:
+            warnings.warn(str(e))
+        return fn
+    return _wrapper

dktasklib/help.py

@@ -0,0 +1,17 @@
+from dktasklib.wintask import task
+
+
+@task(default=True)
+def help(ctx):
+    """
+    """
+    ctx.run('invoke --help')
+
+
+@task(default=True)
+def list(ctx):
+    """Show help, basically an alias for --help.
+    This task can be removed once the fix to this issue is released:
+    https://github.com/pyinvoke/invoke/issues/180
+    """
+    ctx.run('invoke --list')