Merge pull request projectmesa#522 from djmitche/use-click

Use click and add `mesa run`

docs/best-practices.rst

@@ -22,8 +22,8 @@ underscores, such as ``thunder_cats``. Within that directory:
 * ``server.py`` should contain the visualization support, including the server
   class.
 
-* ``run.py`` is a Python script that will run the model when invoked as
-  ``python run.py``.
+* ``run.py`` is a Python script that will run the model when invoked via
+  ``mesa run``.
 
 After the number of files grows beyond a half-dozen, try to use sub-folders to
 organize them. For example, if the visualization uses image files, put those in

docs/index.rst

@@ -40,11 +40,11 @@ Getting started quickly:
 
     $ pip install mesa
 
-To launch an example model, open any of the directories in the `examples <https://github.com/projectmesa/mesa/tree/master/examples>`_ folder and launch the ``run.py`` file there, e.g.:
+To launch an example model, clone the `repository <https://github.com/projectmesa/mesa>`_ folder and invoke ``mesa run`` for one of the ``examples/`` subdirectories:
 
 .. code-block:: bash
 
-    schelling $ python run.py
+    schelling $ mesa run examples/wolf_sheep
 
 For more help on using Mesa, check out the following resources:
 

examples/Schelling/README.md

@@ -16,10 +16,10 @@ To install the dependencies use pip and the requirements.txt in this directory.
 
 ## How to Run
 
-To run the model interactively, run ``run.py`` in this directory. e.g.
+To run the model interactively, run ``mesa run`` in this directory. e.g.
 
 ```
-    $ python run.py
+    $ mesa run
 ```
 
 Then open your browser to [http://127.0.0.1:8521/](http://127.0.0.1:8521/) and press Reset, then Run.

examples/bank_reserves/Readme.md

@@ -22,10 +22,10 @@ To install the dependencies use pip and the requirements.txt in this directory.
 
 ## Interactive Model Run
 
-To run the model interactively, run ``run.py`` in this directory. e.g.
+To run the model interactively, use `mesa run` in this directory:
 
 ```
-    $ python run.py
+    $ mesa run
 ```
 
 Then open your browser to [http://127.0.0.1:8521/](http://127.0.0.1:8521/), select the model parameters, press Reset, then Start.

examples/boid-flockers/Readme.md

@@ -28,7 +28,7 @@ Then open your browser to [http://127.0.0.1:8521/](http://127.0.0.1:8521/) and p
 =======
 * Launch the visualization
 ```
-$ python run.py
+$ mesa run
 ```
 * Visit your browser: http://127.0.0.1:8521/
 * In your browser hit *run*

examples/boltzmann_wealth_model_network/README.md

@@ -22,10 +22,10 @@ To install the dependencies use pip and the requirements.txt in this directory.
 
 ## How to Run
 
-To run the model interactively, run ``run.py`` in this directory. e.g.
+To run the model interactively, run ``mesa run`` in this directory. e.g.
 
 ```
-    $ python run.py
+    $ mesa run
 ```
 
 Then open your browser to [http://127.0.0.1:8521/](http://127.0.0.1:8521/) and press Reset, then Run.
@@ -45,4 +45,4 @@ This model is drawn from econophysics and presents a statistical mechanics appro
 
 [Milakovic, M. A Statistical Equilibrium Model of Wealth Distribution. February, 2001.](https://editorialexpress.com/cgi-bin/conference/download.cgi?db_name=SCE2001&paper_id=214)
 
-[Dragulescu, A and Yakovenko, V. Statistical Mechanics of Money, Income, and Wealth: A Short Survey. November, 2002](http://arxiv.org/pdf/cond-mat/0211175v1.pdf)
+[Dragulescu, A and Yakovenko, V. Statistical Mechanics of Money, Income, and Wealth: A Short Survey. November, 2002](http://arxiv.org/pdf/cond-mat/0211175v1.pdf)

examples/color_patches/Readme.md

@@ -18,10 +18,10 @@ An agent's state represents its "opinion" and is shown by the color of the cell
 
 ## How to Run
 
-To run the model interactively, run ``run.py`` in this directory. e.g.
+To run the model interactively, run ``mesa run`` in this directory. e.g.
 
 ```
-    $ python run.py
+    $ mesa run
 ``` 
 
 Then open your browser to [http://127.0.0.1:8521/](http://127.0.0.1:8521/) and press Reset, then Run. 

examples/conways_game_of_life/Readme.md

@@ -9,10 +9,10 @@ The "game" is a zero-player game, meaning that its evolution is determined by it
 
 ## How to Run
 
-To run the model interactively, run ``run.py`` in this directory:
+To run the model interactively, run ``mesa run`` in this directory. e.g.
 
 ```
-    $ python run.py
+    $ mesa run
 ``` 
 
 Then open your browser to [http://127.0.0.1:8521/](http://127.0.0.1:8521/) and press ``run``. 

examples/forest_fire/readme.md

@@ -6,10 +6,10 @@ The [forest fire model](http://en.wikipedia.org/wiki/Forest-fire_model) is a sim
 
 ## How to Run
 
-Launch an interactive server by Running ``run.py``:
+To run the model interactively, run ``mesa run`` in this directory. e.g.
 
 ```
-    $ python run.py
+    $ mesa run
 ```
 
 Then open your browser to [http://127.0.0.1:8521/](http://127.0.0.1:8521/) and press Reset, then Run. 

examples/hex_snowflake/Readme.md

@@ -7,10 +7,10 @@ In this model, each dead cell will become alive if it has exactly one neighbor.
 
 ## How to Run
 
-To run the model interactively, run ``run.py`` in this directory:
+To run the model interactively, run ``mesa run`` in this directory. e.g.
 
 ```
-    $ python run.py
+    $ mesa run
 ```
 
 Then open your browser to [http://127.0.0.1:8521/](http://127.0.0.1:8521/) and press ``run``.

examples/pd_grid/readme.md

@@ -19,7 +19,7 @@ The Demographic Prisoner's Dilemma demonstrates how simple rules can lead to the
 
 ##### Web based model simulation
 
-Run ``python run.py``.
+To run the model interactively, run ``mesa run`` in this directory.
 
 ##### Jupyter Notebook
 

examples/shape_example/Readme.md

@@ -25,10 +25,10 @@ e.g.
 
 ## How to Run
 
-To run the model interactively, run ``run.py`` in this directory. e.g.
+To run the model interactively, run ``mesa run`` in this directory. e.g.
 
 ```
-    $ python run.py
+    $ mesa run
 ```
 
 Then open your browser to [http://127.0.0.1:8521/](http://127.0.0.1:8521/) and

examples/sugarscape_cg/Readme.md

@@ -33,10 +33,10 @@ To install the dependencies use pip and the requirements.txt in this directory.
 
 ## How to Run
 
-To run the model interactively, run ``run.py`` in this directory. e.g.
+To run the model interactively, run ``mesa run`` in this directory. e.g.
 
 ```
-    $ python run.py
+    $ mesa run
 ```
 
 Then open your browser to [http://127.0.0.1:8521/](http://127.0.0.1:8521/) and press Reset, then Run.

examples/virus_on_network/README.md

@@ -18,10 +18,10 @@ To install the dependencies use pip and the requirements.txt in this directory.
 
 ## How to Run
 
-To run the model interactively, run ``run.py`` in this directory. e.g.
+To run the model interactively, run ``mesa run`` in this directory. e.g.
 
 ```
-    $ python run.py
+    $ mesa run
 ```
 
 Then open your browser to [http://127.0.0.1:8521/](http://127.0.0.1:8521/) and press Reset, then Run.

examples/wolf_sheep/Readme.md

@@ -24,10 +24,10 @@ To install the dependencies use pip and the requirements.txt in this directory.
 
 ## How to Run
 
-To run the model interactively, run ``run.py`` in this directory. e.g.
+To run the model interactively, run ``mesa run`` in this directory. e.g.
 
 ```
-    $ python run.py
+    $ mesa run
 ```
 
 Then open your browser to [http://127.0.0.1:8521/](http://127.0.0.1:8521/) and press Reset, then Run.

mesa/main.py

@@ -0,0 +1,26 @@
+import sys
+import os
+import click
+
+PROJECT_PATH = click.Path(exists=True, file_okay=False, dir_okay=True, resolve_path=True)
+
+
+@click.group()
+def cli():
+    'Manage Mesa projects'
+
+
+@cli.command()
+@click.argument('project', type=PROJECT_PATH, default='.')
+def run(project):
+    '''Run mesa project PROJECT
+
+    PROJECT is the path to the directory containing `run.py`, or the current
+    directory if not specified.
+    '''
+    sys.path.insert(0, project)
+    os.chdir(project)
+
+    with open("run.py") as f:
+        code = compile(f.read(), "run.py", 'exec')
+        exec(code, {}, {})

requirements.txt

@@ -9,5 +9,5 @@ tornado==4.5.3
 flake8==2.5.2
 tqdm
 networkx==2.1
-
+click==6.7
 

setup.py

@@ -10,6 +10,7 @@
     'numpy',
     'pandas',
     'tqdm',
+    'click',
 ]
 
 version = ''
@@ -47,4 +48,8 @@
         'Development Status :: 3 - Alpha',
         'Natural Language :: English',
     ],
+    entry_points='''
+        [console_scripts]
+        mesa=mesa.main:cli
+    ''',
 )

tests/test_main.py

@@ -0,0 +1,28 @@
+import os
+import sys
+import unittest
+from unittest.mock import patch
+from click.testing import CliRunner
+
+from mesa.main import cli
+
+
+class TestCli(unittest.TestCase):
+    '''
+    Test CLI commands
+    '''
+
+    def setUp(self):
+        self.old_sys_path = sys.path[:]
+        self.runner = CliRunner()
+
+    def tearDown(self):
+        sys.path[:] = self.old_sys_path
+
+    def test_run(self):
+        with patch('mesa.visualization.ModularVisualization.ModularServer') as ModularServer:
+            example_dir = os.path.abspath(os.path.join(os.path.dirname(__file__), '../examples/wolf_sheep'))
+            with self.runner.isolated_filesystem():
+                result = self.runner.invoke(cli, ['run', example_dir])
+                assert result.exit_code == 0, result.output
+                assert ModularServer().launch.call_count == 1