From b8b521adf23803f2303c60d6e611f98e34c3a2c1 Mon Sep 17 00:00:00 2001 From: Mostapha Date: Fri, 6 Sep 2019 09:36:32 -0400 Subject: [PATCH] feat(cli): add cli to honeybee This commit adds a minimal but extendable command line interface to honeybee. I'm using click to create the `cli` which gives us a great level of flexibility and fits our needs for ladybug tools. Since the command line interface might not be needed for all the installations I added click to setup.py as an `extra_requires` for `cli`. One needs to use `pip install honeybee-core[cli]` or `pip install honeybee-core[all]` to install both honeybee core and the cli dependencies. --- MANIFEST.in | 1 - README.md | 39 +++++++++++++--------- dev-requirements.txt | 1 + docs/cli.rst | 6 ++++ docs/conf.py | 7 ++-- docs/index.rst | 38 ++++++++++++++++++--- honeybee/__init__.py | 25 +++++++------- honeybee/__main__.py | 4 +++ honeybee/cli.py | 78 ++++++++++++++++++++++++++++++++++++++++++++ setup.py | 11 +++++-- 10 files changed, 170 insertions(+), 40 deletions(-) delete mode 100644 MANIFEST.in create mode 100644 docs/cli.rst create mode 100644 honeybee/__main__.py create mode 100644 honeybee/cli.py diff --git a/MANIFEST.in b/MANIFEST.in deleted file mode 100644 index f9bd1455..00000000 --- a/MANIFEST.in +++ /dev/null @@ -1 +0,0 @@ -include requirements.txt diff --git a/README.md b/README.md index 9244923c..1432e79a 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -![Honeybee](http://www.ladybug.tools/assets/img/honeybee.png) +![Honeybee](https://www.ladybug.tools/assets/img/honeybee.png) [![Build Status](https://travis-ci.org/ladybug-tools/honeybee-core.svg?branch=master)](https://travis-ci.org/ladybug-tools/honeybee-core) [![Coverage Status](https://coveralls.io/repos/github/ladybug-tools/honeybee-core/badge.svg?branch=master)](https://coveralls.io/github/ladybug-tools/honeybee-core) @@ -7,24 +7,33 @@ # honeybee-core -Honeybee core library. +Honeybee is a collection of Python libraries to create, run and visualize +daylight ([RADIANCE](https://radiance-online.org//)) and energy +([EnergyPlus](https://energyplus.net/)/[OpenStudio](https://www.openstudio.net/)) models. -# NOTE +This repository is the core repository that provides honeybee's common functionalities. +To extend these functionalities you should install available Honeybee extensions or write +your own. -This repository will be renamed to `honeybee` once the current `honeybee` repository is -renamed to `honeybee-radiance`. +Here are a number of frequently used extensions for Honeybee: -## What is this repository? +- [honeybee-energy](https://github.com/ladybug-tools/honeybee-energy): Adds Energy simulation to Honeybee. +- [honeybee-radiance](https://github.com/ladybug-tools/honeybee-radiance): Adds daylight simulation to Honeybee. -Honeybee is a collection of Python library to create, run and visualize the results of -daylight ([RADIANCE](https://radiance-online.org//)) and energy analysis -([EnergyPlus](https://energyplus.net/)/[OpenStudio](https://www.openstudio.net/)). -This repository is the main repository for Honeybee core libraries. To extend the -functionalities of this library you should install available Honeybee extensions or write -your own. See [here](https://github.com/ladybug-tools/honeybee-extension) to get started -with writing your first extension. +# Installation -Here are a number of available extensions for Honeybee: +To install the core library try: -- [honeybee-energy](https://github.com/ladybug-tools/honeybee-energy): Adds Energy simulation to Honeybee. +`pip install -U honeybee-core` + +If you want to also include the command line interface try: + +`pip install -U honeybee-core[cli]` + +To check if Honeybee command line is installed correctly try `honeybee viz` and you +should get a `viiiiiiiiiiiiizzzzzzzzz!` back in response! :bee: + +# Documentation + +[API documentation](https://www.ladybug.tools/honeybee-core/docs/) diff --git a/dev-requirements.txt b/dev-requirements.txt index 5a5fd4e2..8ef9184c 100644 --- a/dev-requirements.txt +++ b/dev-requirements.txt @@ -6,4 +6,5 @@ Sphinx==1.8.5 sphinx-bootstrap-theme==0.6.5 sphinxcontrib-fulltoc==1.2.0 sphinxcontrib-websupport==1.1.0 +sphinx-click==2.2.0 twine==1.13.0 diff --git a/docs/cli.rst b/docs/cli.rst new file mode 100644 index 00000000..ddd93832 --- /dev/null +++ b/docs/cli.rst @@ -0,0 +1,6 @@ +honeybee command line interface +=============================== + +.. click:: honeybee.cli:main + :prog: honeybee + :show-nested: diff --git a/docs/conf.py b/docs/conf.py index 71173f45..ca47c65a 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -14,7 +14,7 @@ # import os import sys -sys.path.insert(0, os.path.abspath('../')) +sys.path.insert(0, os.path.abspath('..')) # -- Project information ----------------------------------------------------- @@ -46,8 +46,9 @@ 'sphinx.ext.ifconfig', 'sphinx.ext.viewcode', 'sphinx.ext.githubpages', - 'sphinxcontrib.fulltoc', - 'sphinx.ext.napoleon' + 'sphinxcontrib.fulltoc', + 'sphinx.ext.napoleon', + 'sphinx_click.ext' ] # Add any paths that contain templates here, relative to this directory. diff --git a/docs/index.rst b/docs/index.rst index 70b747c2..64b64610 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,16 +1,44 @@ -.. Honeybee documentation master file, created by - sphinx-quickstart on Wed Mar 13 20:09:41 2019. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. Welcome to Honeybee's documentation! -=================================== +========================================= + +.. image:: http://www.ladybug.tools/assets/img/honeybee.png + +Honeybee is a collection of Python libraries to create, run and visualize the results of +daylight `RADIANCE `_ and energy analysis +`EnergyPlus `_ / `OpenStudio `_. + +Installation +============ + +To install the core library try ``pip install -U honeybee-core``. + +If you want to also include the command line interface try ``pip install -U honeybee-core[cli]``. + +To check if the Honeybee command line is installed correctly try ``honeybee viz`` and you +should get a ``viiiiiiiiiiiiizzzzzzzzz!`` back in response! + + +Documentation +============= + +This document includes `Honeybee API documentation <#honeybee>`_ and +`Honeybee Command Line Interface <#id1>`_ documentation for ``honeybee core`` and does +not include the documentation for honeybee extensions. For each extension refer to +extension's documentation page. + +Here are a number of Honeybee popular extensions: + +- `honeybee-energy `_ +- `honeybee-radiance `_ + .. toctree:: :maxdepth: 2 :caption: Contents: .. include:: modules.rst +.. include:: cli.rst Indices and tables diff --git a/honeybee/__init__.py b/honeybee/__init__.py index 710c5961..ebe1ef41 100644 --- a/honeybee/__init__.py +++ b/honeybee/__init__.py @@ -2,19 +2,18 @@ import sys import importlib import pkgutil - +import logging # find and import honeybee extensions # this is a critical step to add additional functionalities to honeybee core library. -extensions = { - name: importlib.import_module(name) - for finder, name, ispkg - in pkgutil.iter_modules() - if name.startswith('honeybee_') -} - -for key in extensions: - print('Successfully imported: {}'.format(key)) - -# This is a variable to check if the library is a [+] library. -setattr(sys.modules[__name__], 'isplus', False) +extensions = {} +for finder, name, ispkg in pkgutil.iter_modules(): + if not name.startswith('honeybee_'): + continue + try: + extensions[name] = importlib.import_module(name) + except Exception: + print( + 'Failed to import {0}!' + ' To see full error message try `import {0}`'.format(name) + ) diff --git a/honeybee/__main__.py b/honeybee/__main__.py new file mode 100644 index 00000000..a0f39897 --- /dev/null +++ b/honeybee/__main__.py @@ -0,0 +1,4 @@ +from honeybee.cli import main + +if __name__ == '__main__': + main() diff --git a/honeybee/cli.py b/honeybee/cli.py new file mode 100644 index 00000000..99182d07 --- /dev/null +++ b/honeybee/cli.py @@ -0,0 +1,78 @@ +""" +Command Line Interface (CLI) entry point for honeybee and honeybee extensions. + +Use this file only to add command related to honeybee-core. For adding extra commands +from each extention see below. + +Honeybee is using click (https://click.palletsprojects.com/en/7.x/) for creating the CLI. +You can extend the command line interface from inside each extention by following these +steps: + +1. Create a ``cli.py`` file in your extension. +2. Import the ``main`` function from this ``honeybee.cli``. +3. Add your commands and command groups to main using add_command method. +4. Add ``import [your-extention].cli`` to ``__init__.py`` file to the commands are added + to the cli when the module is loaded. + +The good practice is to group all your extention commands in a command group named after +the extension. This will make the commands organized under extension namespace. For +instance commands for `honeybee-radiance` will be called like ``honeybee radiance [radiance-command]``. + + +.. code-block:: python + + import click + from honeybee.cli import main + + @click.group() + def radiance(): + pass + + # add commands to radiance group + @radiance.command('daylight-factor') + # ... + def daylight_factor(): + pass + + + # finally add the newly created commands to honeybee cli + main.add_command(radiance) + + # do not forget to import this module in __init__.py otherwise it will not be added + # to honeybee commands. + +Note: + + For extension with several commands you can use a folder structure instead of a single + file. Refer to ``honeybee-radiance`` for an example. + +""" + +try: + import click +except ImportError: + raise ImportError( + 'click module is not installed. Try `pip install honeybee-core[cli]` command.' + ) +import importlib +import sys +import logging +import honeybee + +# use this logger for logging inside this file and all the extensions +_logger = logging.getLogger(__name__) + +@click.group() +@click.version_option() +def main(): + pass + + +@main.command('viz') +def viz(): + """Check if honeybee is flying!""" + click.echo('viiiiiiiiiiiiizzzzzzzzz!') + + +if __name__ == "__main__": + main() diff --git a/setup.py b/setup.py index 992e72a3..759563f0 100644 --- a/setup.py +++ b/setup.py @@ -1,6 +1,5 @@ import re import setuptools -import sys with open("README.md", "r") as fh: long_description = fh.read() @@ -10,16 +9,22 @@ setuptools.setup( name="honeybee-core", - use_scm_version = True, + use_scm_version=True, setup_requires=['setuptools_scm'], author="Ladybug Tools", author_email="info@ladybug.tools", - description="Honeybee is a Python library to create, run and visualize the results of environmental simulation. See plugins (e.g. honeybee_radiance) for specific simulation type.", + description="Honeybee is a Python library to create, run and visualize the results of environmental simulation. See extensions (e.g. honeybee_radiance) for specific simulation type.", long_description=long_description, long_description_content_type="text/markdown", url="https://github.com/ladybug-tools/honeybee-core", packages=setuptools.find_packages(exclude=["tests"]), install_requires=requirements, + extra_requires={ + 'cli': ['click>=5.1'] + }, + entry_points={ + "console_scripts": ["honeybee = honeybee.cli:main"] + }, classifiers=[ "Programming Language :: Python :: 2.7", "Programming Language :: Python :: 3.6",