Merge pull request #555 from msqd/create_cli

[FEATURE] CLI: harp create project
msqd · Oct 28, 2024 · 7677598 · 7677598
2 parents b9c0575 + 131adda
commit 7677598
Show file tree

Hide file tree

Showing 26 changed files with 3,278 additions and 573 deletions.
diff --git a/docs/_quicktoc.rst b/docs/_quicktoc.rst
@@ -37,10 +37,10 @@
     |                                                        |                                                        |
     | Enhance and extend.                                    | Dive in the internals.                                 |
     |                                                        |                                                        |
-    | - :doc:`/develop/run`                                  | - :doc:`/contribute/introduction`                      |
-    | - :doc:`/develop/customize`                            | - :doc:`/contribute/overview`                          |
-    | - :doc:`/develop/extend`                               | - :doc:`/contribute/dependency-injection`              |
-    |                                                        | - :doc:`/contribute/events`                            |
+    | - :doc:`/develop/quick-start`                          | - :doc:`/contribute/introduction`                      |
+    | - :doc:`/develop/run`                                  | - :doc:`/contribute/overview`                          |
+    | - :doc:`/develop/customize`                            | - :doc:`/contribute/dependency-injection`              |
+    | - :doc:`/develop/extend`                               | - :doc:`/contribute/events`                            |
     |                                                        | - :doc:`/contribute/applications`                      |
     +--------------------------------------------------------+--------------------------------------------------------+
     | :doc:`Reference </reference/index>`                                                                             |

diff --git a/docs/changelogs/unreleased.rst b/docs/changelogs/unreleased.rst
@@ -1,6 +1,7 @@
 Unreleased
 ==========
 
+* CLI: adds a cookiecutter based «harp create project» command to bootstrap an empty proxy project.
 * Config: «!include» constructor can now be used in all configuration files, not only service definitions.
 * Proxy: It is now possible to override the default HttpProxyController with your own on a per-endpoint basis.
 * Rules/DX: Better errors on rules failure.

diff --git a/docs/develop/_toc.rst b/docs/develop/_toc.rst
@@ -6,6 +6,7 @@
 .. toctree::
     :maxdepth: 2
 
+    quick-start
     run
     customize
     extend
diff --git a/docs/develop/quick-start.rst b/docs/develop/quick-start.rst
@@ -0,0 +1,44 @@
+Quick Start
+===========
+
+Install & Bootstrap
+:::::::::::::::::::
+
+To start developing with HARP (create your own proxies with custom code), you need a few
+things:
+
+**Install HARP to be used as a CLI/dev tool**
+
+.. code:: shell
+
+    pipx install 'harp-proxy[dev]'
+
+.. note::
+
+    This will install an isolated instance of HARP that we'll mostly use to create new
+    projects. It is possible to do it without, but this is the easiest.
+
+**Bootstrap a new project**
+
+.. code:: shell
+
+    harp create project
+
+Answer a few questions, and you're ready to go!
+
+
+**Start your project**
+
+.. code:: shell
+
+    cd <your-project>
+    make
+
+This will install the dependencies (in a poetry-managed virtualenv) and start your proxy.
+
+Next Steps
+::::::::::
+
+Congratulations, you created your first HARP project! Now you can start tuning it.
+
+.. todo:: pointers
diff --git a/docs/reference/core/harp.commandline.cookiecutters.project.rst b/docs/reference/core/harp.commandline.cookiecutters.project.rst
@@ -0,0 +1,9 @@
+harp.commandline.cookiecutters.project
+======================================
+
+.. automodule:: harp.commandline.cookiecutters.project
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+    .. inheritance-diagram:: harp.commandline.cookiecutters.project
diff --git a/docs/reference/core/harp.commandline.cookiecutters.rst b/docs/reference/core/harp.commandline.cookiecutters.rst
@@ -0,0 +1,17 @@
+harp.commandline.cookiecutters
+==============================
+
+.. automodule:: harp.commandline.cookiecutters
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+    .. inheritance-diagram:: harp.commandline.cookiecutters
+
+Submodules
+----------
+
+.. toctree::
+    :maxdepth: 1
+
+    harp.commandline.cookiecutters.project
diff --git a/docs/reference/core/harp.commandline.rst b/docs/reference/core/harp.commandline.rst
@@ -14,6 +14,7 @@ Submodules
 .. toctree::
     :maxdepth: 1
 
+    harp.commandline.cookiecutters
     harp.commandline.install
     harp.commandline.migrations
     harp.commandline.options

diff --git a/harp/commandline/__init__.py b/harp/commandline/__init__.py
@@ -42,6 +42,7 @@
 from click import Command
 
 from harp.commandline.config import config
+from harp.commandline.create import create
 from harp.commandline.examples import entrypoint as examples
 from harp.commandline.server import server
 from harp.settings import HARP_ENV
@@ -112,6 +113,7 @@ def start(*args, **kwargs):
 entrypoint.add_command(server)
 entrypoint.add_command(config)
 entrypoint.add_command(examples)
+entrypoint.add_command(create)
 
 __all__ = [
     "entrypoint",

diff --git a/harp/commandline/cookiecutters/__init__.py b/harp/commandline/cookiecutters/__init__.py
diff --git a/harp/commandline/cookiecutters/project/LICENSE b/harp/commandline/cookiecutters/project/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 {{cookiecutter.author}}
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/harp/commandline/cookiecutters/project/README.rst b/harp/commandline/cookiecutters/project/README.rst
@@ -0,0 +1,7 @@
+# HARP Cookiecutter Template
+
+.. code:: shell
+
+	cookiecutter gh:msqd/harp-template
+
+Enjoy :)
diff --git a/harp/commandline/cookiecutters/project/__init__.py b/harp/commandline/cookiecutters/project/__init__.py
diff --git a/harp/commandline/cookiecutters/project/cookiecutter.json b/harp/commandline/cookiecutters/project/cookiecutter.json
@@ -0,0 +1,8 @@
+{
+  "name": "HARP Project",
+  "__dir_name": "{{cookiecutter.name | slugify}}",
+  "__pkg_name": "{{cookiecutter.name | slugify(separator='_')}}",
+  "author": "Smart Anonymous Harpist",
+  "create_application": false,
+  "create_config": true
+}
diff --git a/harp/commandline/cookiecutters/project/hooks/post_gen_project.sh b/harp/commandline/cookiecutters/project/hooks/post_gen_project.sh
@@ -0,0 +1,12 @@
+#! /bin/bash
+
+if [ "{{cookiecutter.create_application}}" == "False" ]; then
+    echo "Removing application folder (create_application == False)."
+    rm -rf ./{{cookiecutter.__pkg_name}}
+fi
+
+
+if [ "{{cookiecutter.create_config}}" == "False" ]; then
+    echo "Removing config file (create_config == False)."
+    rm -f ./config.yml
+fi
diff --git a/harp/commandline/cookiecutters/project/{{cookiecutter.__dir_name}}/Makefile b/harp/commandline/cookiecutters/project/{{cookiecutter.__dir_name}}/Makefile
@@ -0,0 +1,10 @@
+POETRY ?= $(shell which poetry || echo poetry)
+
+.PHONY: start install
+
+
+start: install
+	$(POETRY) run harp server{% if cookiecutter.create_application %} --enable {{cookiecutter.__pkg_name}}{% endif %}{% if cookiecutter.create_config %} --file config.yml{% endif %}
+
+install:
+	$(POETRY) install
diff --git a/harp/commandline/cookiecutters/project/{{cookiecutter.__dir_name}}/README.rst b/harp/commandline/cookiecutters/project/{{cookiecutter.__dir_name}}/README.rst
@@ -0,0 +1,7 @@
+Example: {{cookiecutter.name}}
+========={{'=' * cookiecutter.name|length}}
+
+.. code::
+
+	# install dependencies and start your proxy
+	make
diff --git a/harp/commandline/cookiecutters/project/{{cookiecutter.__dir_name}}/__init__.py b/harp/commandline/cookiecutters/project/{{cookiecutter.__dir_name}}/__init__.py
diff --git a/harp/commandline/cookiecutters/project/{{cookiecutter.__dir_name}}/config.yml b/harp/commandline/cookiecutters/project/{{cookiecutter.__dir_name}}/config.yml
@@ -0,0 +1 @@
+{}