Merge pull request #111 from mikofski/quickstart

quickstart and file-structure changes

Author: mikofski

carousel-quickstart.py

@@ -6,12 +6,12 @@
 """
 
 import argparse
-import json
 import logging
 import os
 import re
 from carousel import __version__
 import sys
+from dulwich import porcelain, config as gitconfig
 
 # set up logging
 logging.basicConfig(level=logging.INFO)
@@ -20,31 +20,50 @@
 # constants
 CWD = os.getcwd()
 OKAY = r'[\w\d]'
-LAYERS = ['simulations', 'outputs', 'calculations', 'formulas', 'data']
-DFLT_MODEL = dict.fromkeys(LAYERS)
-DFLT = 'my_model.json'
-MODELS = 'models'
-PATHS = [MODELS] + LAYERS
 INIT_CONTENT = """
 import os
 
 __version__ = '0.1'
-__author__ = 'your name'
-__email__ = 'your.name@company.com'
+__author__ = '%s'
+__email__ = '%s'
 
-PKG_PATH = os.path.abspath(os.path.dirname(__file__))
-PROJ_PATH = os.path.dirname(PKG_PATH)
+PROJ_PATH = os.path.abspath(os.path.dirname(__file__))
+# TODO: change PROJ_PATH to MODELPATH everywhere
 """
 DESCRIPTION = """
-Creates a Carousel project.  See documentation for more information.
+Create a Carousel project file structure. See documentation for more detail.
 """
+GIT_GLOBAL = os.path.expanduser(os.path.join('~', '.gitconfig'))
+UNKNOWN = 'unknown'
+USERNAME = (os.environ.get('USERNAME', UNKNOWN) if sys.platform == 'win32'
+            else os.environ.get('USER', UNKNOWN))  # default username
+HOSTNAME = os.uname()[1]
+USEREMAIL = '%s@%s' % (USERNAME, HOSTNAME)
+
+
+def get_gitconfig(git_path, section, name):
+    try:
+        return gitconfig.ConfigFile.from_path(git_path).get(section, name)
+    except (IOError, KeyError):
+        return None
+
 
 # run from command line
 if __name__ == '__main__':
     parser = argparse.ArgumentParser(description=DESCRIPTION)
     parser.add_argument('project', help='name of Carousel project to create')
     parser.add_argument('--version', action='version',
                         version=('%(prog)s' + ' %s' % __version__))
+    parser.add_argument('-g', '--git', action='store_true',
+                        help='initialize Git repository for project')
+    parser.add_argument(
+        '-f', '--folders', action='append', default=['data'],
+        help=('create layer folders in project package, list each folder'
+              ' separately, can be used more than once, default is "data"'))
+    parser.add_argument('--author', help="Project author's full name",
+                        default=USERNAME)
+    parser.add_argument('--email', help="Project author's email",
+                        default=USEREMAIL)
     args = parser.parse_args()
     # exit with error if no project name specified
     if len(sys.argv) < 2:
@@ -63,16 +82,47 @@
         sys.exit('The path, %s, already exists.' % project_name)
     os.mkdir(project_name)  # make project folder
     LOGGER.info('Project created at path, %s.', project_name)
-    # make project file structure
-    for p in PATHS + [project_pkg]:
-        os.mkdir(os.path.join(project_name, p))
-        LOGGER.debug('created folder: %s', p)
     # make project package
+    os.mkdir(os.path.join(project_name, project_pkg))  # make project package
+    LOGGER.info('Project package, %s, created.', project_pkg)
     pkg_init = os.path.join(project_name, project_pkg, '__init__.py')
+    # try to get user info from git config
+    username = useremail = None
+    if args.author == USERNAME:
+        username = get_gitconfig(GIT_GLOBAL, 'user', 'name')
+        if username:
+            args.author = username
+    if args.email == USEREMAIL:
+        useremail = get_gitconfig(GIT_GLOBAL, 'user', 'email')
+        if useremail:
+            args.email = useremail
     with open(pkg_init, 'w') as init:
         init.write('"""\nThis is the %s package.\n"""\n' % project_pkg)
-        init.write(INIT_CONTENT)
-    # make default model
-    with open(os.path.join(project_name, MODELS, DFLT), 'w') as dflt:
-        json.dump(DFLT_MODEL, dflt, indent=2)
-        LOGGER.debug('created %s in %s/%s', DFLT, project_name, MODELS)
+        init.write(INIT_CONTENT % (args.author, args.email))
+    LOGGER.info('Package file created: %s.', pkg_init)
+    if args.git:
+        repo = porcelain.init(project_name)
+        LOGGER.info('Project Git repository initialized: %s.', repo)
+        porcelain.add(repo, os.path.relpath(pkg_init, project_name))
+        LOGGER.info('Project package added to index')
+        # if global git config username and email not set, use args if specified
+        kwargs = {}
+        if not username:
+            username = args.author
+        if not useremail:
+            useremail = args.email
+        if not os.path.exists(GIT_GLOBAL):
+            conf = repo.get_config()
+            conf.set('user', 'name', username)
+            conf.set('user', 'email', useremail)
+            conf.write_to_path()
+        else:
+            kwargs['author'] = '%s <%s>' % (username, useremail)
+        sha1 = porcelain.commit(repo, message='initial dump', **kwargs)
+        LOGGER.info('Project initial commit: %s.', sha1)
+        porcelain.log(repo, outstream=logging.root.handlers[0].stream)
+    # make project layer folders
+    for fp in args.folders:
+        os.mkdir(os.path.join(project_name, project_pkg, fp))
+        LOGGER.info('created folder: %s', fp)
+    LOGGER.info('Carousel quickstart completed.')

carousel/__init__.py

@@ -45,4 +45,4 @@ def get_current_version(*args, **kwargs):
 __email__ = u'mark.mikofski@sunpowercorp.com'
 __url__ = u'https://github.com/SunPower/Carousel'
 __version__ = VERSION
-__release__ = u'Caramel Corn'
+__release__ = u'Carousel'

carousel/docs/announcements/caramel-corn.rst

@@ -1,7 +1,7 @@
 .. _caramel_corn:
 
-Caramel Corn (v0.3.1)
-=====================
+Caramel Corn CONSTANTS (v0.3.1)
+===============================
 This version is a *major* release with several new features which will break
 previous Carousel models. In particular, the following new features have been
 introduced starting with v0.3:

carousel/docs/announcements/carousel.rst

@@ -0,0 +1,22 @@
+.. _carousel:
+
+Carousel (v0.3.2)
+=================
+
+Quickstart
+----------
+The ``carousel-quickstart`` now only creates a *data* folder, and it puts the
+*data* folder inside the project package. It doesn't create any other folders
+explicitly, and it doesn't create a sample model parameter JSON file. There is
+an option to create additional *layer* folders inside the project package.
+
+The ``carousel-quickstart`` also now provides an option to initialize the
+project as a Git repository. If found it will set the ``__author`` and
+``__email__`` fields in the project package ``__init__.py`` file from either
+the Git global configuration or from system environmental variables.
+
+Setup Dulwich Requirement
+-------------------------
+Also, even though `Dulwich <https://www.dulwich.io/>`_ is now a requirement
+in ``setup.py``, the ``carousel/__init__.py`` file now has a *try/except* block
+around the ``dulwich`` import to make sure that installation goes smoothly.

carousel/docs/api/scripts.rst

@@ -13,24 +13,12 @@ Creates a basic file structure to start a Carousel project. ::
     Project
     |
     +-+- project
-    | |
-    | +- __init__.py
-    |
-    +-+- models
-    | |
-    | +- my_model.json
-    |
-    +- simulation
-    |
-    +- outputs
-    |
-    +- calculations
-    |
-    +- formulas
-    |
-    +- data
+      |
+      +- __init__.py
+      |
+      +- data
 
-The contents of ``project/__init__.py`` is the following::
+The contents of ``Project/project/__init__.py`` is the following::
 
     """
     This is the Project package.
@@ -42,18 +30,7 @@ The contents of ``project/__init__.py`` is the following::
     __author__ = 'your name'
     __email__ = 'your.name@company.com'
 
-    PKG_PATH = os.path.abspath(os.path.dirname(__file__))
-    PROJ_PATH = os.path.dirname(PKG_PATH)
-
-An empty model is contained in ``models/my_model.json``. ::
-
-    {
-      "outputs": null,
-      "formulas": null,
-      "data": null,
-      "calculations": null,
-      "simulations": null
-    }
+    PROJ_PATH = os.path.abspath(os.path.dirname(__file__))
 
 Call ``carousel-quickstart.py`` from the command line to see usage, help and
 version information. Some more detail is also given in :ref:`getting-started`.

carousel/docs/getting_started.rst

@@ -15,37 +15,22 @@ project. ::
 
     $ carousel-quickstart.py MyCarouselProject.
 
-This creates a new folder for ``MyCarouselProject`` with seven
-sub-folders. ::
+This creates a new folder for ``MyCarouselProject``, a Python package with the
+same name, and a *data* folder. ::
 
     MyCarouselProject
     |
     +-+- mycarouselproject
-    | |
-    | +- __init__.py
-    |
-    +-+- models
-    | |
-    | +- my_model.json
-    |
-    +- simulation
-    |
-    +- outputs
-    |
-    +- calculations
-    |
-    +- formulas
-    |
-    +- data
+      |
+      +- __init__.py
+      |
+      +- data
 
 The quickstart script adds the constant ``mycarouselproject.PROJ_PATH`` that
-refers to the project path ``MyCarouselProject/``. This path is useful, as we'll
-see in the :ref:`next tutorial <tutorial-1>`, and should be imported into the
-project package modules. The script also adds version, author and email
-information that you can complete if you want. Finally a sample model parameter
-file is created in ``MyCarouselProject/models/my_model.json`` - feel free to
-delete this if not used. The sample parameter file is used in the legacy style
-described in the :ref:`parameter-styles` section below.
+refers to the project path ``MyCarouselProject/mycarouselproject``. This path is
+useful, as we'll see in the :ref:`next tutorial <tutorial-1>`, and should be
+imported into the project package modules. The script also adds version, author
+and email information that you can complete if you want.
 
 .. _tutorials:
 

carousel/docs/index.rst

@@ -56,6 +56,7 @@ Announcements
 .. toctree::
    :maxdepth: 2
 
+   announcements/carousel
    announcements/caramel-corn
    announcements/brown-bicycle-bears
 

carousel/docs/tutorials/tutorial_3.rst

@@ -13,8 +13,10 @@ Carousel currently supports formulas that are written in Python as function
 definitions or strings that can be evaluated by the Python
 `numexpr <https://pypi.python.org/pypi/numexpr>`_ package. For the PV system
 power example, we will use formulas written as Python functions. To add the
-formulas we need for this example create a Python module in our project formulas
-folder called ``utils.py`` and copy the following code. ::
+formulas we need for this example create a Python package in our project package
+called ``formulas``, don't forget to add ``__init__.py`` to make it a package,
+and copy the following code into a Python module called ``utils.py`` inside the
+formulas folder, *i.e.*: ``PVPower/pvpower/formulas/utils.py``. ::
 
     # -*- coding: utf-8 -*-
 
@@ -131,7 +133,7 @@ that the formulas have the same names as the Python functions. ::
 
         class Meta:
             module = ".utils"
-            package = "formulas"
+            package = "pvpower.formulas"
 
 
 Formula Attributes
@@ -183,22 +185,22 @@ formulas. Otherwise specify the path to the module or package as well. ::
         class Meta:
             formula_importer = PyModuleImporter
             module = '.utils'  # relative module name
-            package = 'formulas'  # module package
-            path = 'examples/PVPower'  # path to package
+            package = 'pvpower.formulas'  # module package
+            path = 'examples/PVPower'  # path to package if not on PYTHONPATH
 
 
     class Irradiance(Formula):
         class Meta:
             formula_importer = PyModuleImporter
             module = 'irradiance'  # module name
             package = None # no package
-            path = 'examples/PVPower/formulas'  # path to module
+            path = 'examples/PVPower/pvpower/formulas'  # path to module
 
 
     class Performance(formulas.Formula):
         class Meta:
             formula_importer = PyModuleImporter
-            module = 'formulas.performance'  # full module name including package
+            module = 'pvpower.formulas.performance'  # module name with package
             package = None
             path = 'examples/PVPower'  # path to package
 

carousel/docs/tutorials/tutorial_5.rst

@@ -182,20 +182,22 @@ for ``PVPowerData``, like Tuscon data, then we could declare it in the model. ::
 
     data = [(PVPowerData, {'filename': 'Tuscon.json'})]
 
-
 Model Path
 ~~~~~~~~~~
-The ``modelpath`` is a legacy attribute that is used with the folder structure
-that is created by ``carousel-quickstart``. It iss confusing since it's called
-*model path* not *project path*, but it refers to the project path that contains
-the model package and the layer folders created by ``carousel-quickstart``. Ha!
-Ha! Ha! The value of ``modelpath`` sets the relative path for to look for files
-loaded by :class:`~carousel.core.layers.Layer`. For new parameter style models
-this is actually only used by the data layer, which looks in project data folder
-created by ``carousel-quickstart``, unless ``path`` is passed as a ``sources``
-argument, and then it looks in ``os.path.join(modelpath, 'data', path)``. So,
-still confused? Just set ``modelpath`` to the name of the folder containing the
-data folder and hopefully you'll be okay. Sorry.
+The ``modelpath`` is an attribute that is used with the folder structure that is
+created by ``carousel-quickstart``. You should set this to the ``PROJ_PATH``
+module constant created in your project package by ``carousel-quickstart``.
+It's confusing since the attribute is *model path* not *project path*, but
+refers to the path that contains the layer folders created by
+``carousel-quickstart``. The value of ``modelpath`` is prepended to the name of
+the layer to set the relative path to look for files loaded by each
+:class:`~carousel.core.layers.Layer`. For new parameter style models this is
+actually only used by the data layer, since the model looks in the project
+*data* folder created by ``carousel-quickstart``, unless ``path`` is passed as a
+``sources`` argument, then it appends the value of ``path`` to the relative
+path. So, still confused? Just set ``modelpath`` to the name of the folder
+containing the *data* folder, which should be ``PROJ_PATH`` if you used
+``carousel-quickstart``, and you'll be okay.
 
 Running Model Simulation
 ------------------------

carousel/tests/__init__.py

@@ -12,11 +12,12 @@
 PROJECT = 'PVPower'
 MODEL = 'sandia_performance_model'
 TESTS_DIR = os.path.abspath(os.path.dirname(__file__))
-PROJ_PATH = os.path.abspath(os.path.join(
+PKG_PATH = os.path.abspath(os.path.join(
     TESTS_DIR, '..', '..', 'examples', PROJECT
 ))
+PROJ_PATH = os.path.join(PKG_PATH, PROJECT.lower())
 
-sys.path.append(PROJ_PATH)
+sys.path.append(PKG_PATH)
 sandia_performance_model = importlib.import_module(
     '.%s' % MODEL, PROJECT.lower()
 )