Merge pull request #108 from UDST/settings-objects

[0.2.dev6] Introducing settings objects

.travis.yml

@@ -10,12 +10,8 @@ matrix:
     - python: '3.7'  # temp solution until python 3.7 is more cleanly supported
       dist: xenial
       sudo: true
-  allow_failures:
-    - python: '3.7'  # dependencies are blocking installation
-  fast_finish: true
 
 install:
-  - pip install git+git://github.com/udst/choicemodels.git
   - pip install .
   - pip install -r requirements-extras.txt
   - pip install -r requirements-dev.txt

CHANGELOG.md

@@ -2,9 +2,15 @@
 
 ## 0.2 (not yet released)
 
+#### 0.2.dev6 (2019-04-04)
+
+- introduces classes for storing common settings: `shared.CoreTemplateSettings`, `shared.OutputColumnSettings`
+- adds new shared functions: `shared.register_column()`, `utils.cols_in_expression()`
+- modifies `ColumnFromExpression` template to divide its parameters into three groups
+
 #### 0.2.dev5 (2019-03-29)
 
-- adds new template: `urbansim_templates.data.ColumnFromExpression`
+- adds new template: `data.ColumnFromExpression`
 
 #### 0.2.dev4 (2019-03-26)
 
@@ -20,16 +26,16 @@
 
 #### 0.2.dev2 (2019-03-04)
 
-- adds template for saving data: `urbansim_templates.data.SaveTable()`
-- renames `TableFromDisk()` to `urbansim_templates.data.LoadTable()`
+- adds template for saving data: `data.SaveTable()`
+- renames `io.TableFromDisk()` to `data.LoadTable()`
 
 #### 0.2.dev1 (2019-02-27)
 
 - fixes a crash in small MNL simulation
 
 #### 0.2.dev0 (2019-02-19)
 
-- adds first data i/o template: `urbansim_templates.io.TableFromDisk()`
+- adds first data i/o template: `io.TableFromDisk()`
 - adds support for `autorun` template property
 
 

docs/source/conf.py

@@ -37,6 +37,7 @@
 # ones.
 extensions = [
     'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
     'sphinx.ext.napoleon',
     'sphinx.ext.viewcode']
 

docs/source/data-templates.rst

@@ -1,13 +1,10 @@
-Data template APIs
-==================
+Data management templates
+=========================
 
 Usage
 -----
 
-Data templates help you load tables into `Orca <https://udst.github.io/orca>`__ or save tables or subsets of tables to disk. 
-
-Example
-~~~~~~~
+Data templates help you load tables into `Orca <https://udst.github.io/orca>`__, create columns of derived data, or save tables or subsets of tables to disk. 
 
 .. code-block:: python
     
@@ -75,22 +72,42 @@ From Orca's perspective, tables set up using the :mod:`~urbansim_templates.data.
 Unlike the templates, Orca relies on user-specified "`broadcast <http://udst.github.io/orca/core.html#merge-api>`__" relationships to perform automatic merging of tables. :mod:`~urbansim_templates.data.LoadTable` does not register any broadcasts, because they're not needed if tables follow the schema rules above. So if you use these tables in non-template model steps, you may need to add broadcasts separately.
 
 
-LoadTable()
------------
+Data loading API
+----------------
+
+.. currentmodule:: urbansim_templates.data
+
+.. autosummary::
+    LoadTable
 
 .. autoclass:: urbansim_templates.data.LoadTable
    :members:
 
 
-SaveTable()
------------
+Column creation API
+-------------------
 
-.. autoclass:: urbansim_templates.data.SaveTable
+.. currentmodule:: urbansim_templates.data
+
+.. autosummary::
+    ColumnFromExpression
+    ExpressionSettings
+
+.. autoclass:: urbansim_templates.data.ColumnFromExpression
    :members:
 
+.. autoclass:: urbansim_templates.data.ExpressionSettings
+   :members:
 
-ColumnFromExpression()
-----------------------
+Data output API
+---------------
 
-.. autoclass:: urbansim_templates.data.ColumnFromExpression
+.. currentmodule:: urbansim_templates.data
+
+.. autosummary::
+    SaveTable
+
+.. autoclass:: urbansim_templates.data.SaveTable
    :members:
+
+

docs/source/index.rst

@@ -10,7 +10,7 @@ UrbanSim Templates provides building blocks for Orca-based simulation models. It
 
 The library contains templates for common types of model steps, plus a tool called ModelManager that runs as an extension to the `Orca <https://udst.github.io/orca>`__ task orchestrator. ModelManager can register template-based model steps with the orchestrator, save them to disk, and automatically reload them for future sessions.
 
-v0.2.dev5, released March 29, 2019
+v0.2.dev6, released April 4, 2019
 
 
 Contents

docs/source/utilities.rst

@@ -1,32 +1,87 @@
-Utilities API
-=============
+Shared utilities
+================
 
 The utilities are mainly helper functions for templates. 
 
 
-Template validation
--------------------
+General template tools API
+--------------------------
 
-.. automodule:: urbansim_templates.utils
-   :members: validate_template
+.. currentmodule:: urbansim_templates.shared
+
+.. autosummary::
+    CoreTemplateSettings
+
+.. automodule:: urbansim_templates.shared
+   :members: CoreTemplateSettings
+
+
+Column output tools API
+-----------------------
 
+.. currentmodule:: urbansim_templates.shared
 
-Table schemas and merging
--------------------------
+.. autosummary::
+    OutputColumnSettings
+    register_column
+
+.. automodule:: urbansim_templates.shared
+   :members: OutputColumnSettings, register_column
+
+
+Table schemas and merging API
+-----------------------------
+
+.. currentmodule:: urbansim_templates.utils
+
+.. autosummary::
+    validate_table
+    validate_all_tables
+    merge_tables
 
 .. automodule:: urbansim_templates.utils
    :members: validate_table, validate_all_tables, merge_tables
 
 
-Other helper functions
-----------------------
+Other helper functions API
+--------------------------
+
+.. currentmodule:: urbansim_templates.utils
+
+.. autosummary::
+    all_cols
+    cols_in_expression
+    get_data
+    get_df
+    trim_cols
+    to_list
+    update_column
+    update_name
 
 .. automodule:: urbansim_templates.utils
-   :members: all_cols, get_data, get_df, trim_cols, update_column, to_list, update_column, update_name
+   :members: all_cols, cols_in_expression, get_data, get_df, trim_cols, to_list, update_column, update_name
+
+
+Spec validation API
+-------------------
+
+.. currentmodule:: urbansim_templates.utils
+
+.. autosummary::
+    validate_template
+
+.. automodule:: urbansim_templates.utils
+   :members: validate_template
+
+
+Version management API
+----------------------
 
+.. currentmodule:: urbansim_templates.utils
 
-Version management
-------------------
+.. autosummary::
+    parse_version
+    version_greater_or_equal
 
 .. automodule:: urbansim_templates.utils
    :members: parse_version, version_greater_or_equal

setup.py

@@ -6,7 +6,7 @@
 
 setup(
     name='urbansim_templates',
-    version='0.2.dev5',
+    version='0.2.dev6',
     description='UrbanSim extension for managing model steps',
     author='UrbanSim Inc.',
     author_email='[email protected]',