docs: split ideas into multiple TOML files

docs/ideas/lab.py

@@ -0,0 +1,55 @@
+"""Laboratory of Nitpick ideas."""
+import json
+from pathlib import Path
+from pprint import pprint
+
+import click
+import jmespath
+
+from nitpick.formats import TOMLFormat, YAMLFormat
+from nitpick.generic import flatten, search_dict
+
+workflow = YAMLFormat(path=Path(".github/workflows/python.yaml"))
+
+
+def find(expression):
+    """Find with JMESpath."""
+    print(f"\nExpression: {expression}")
+    rv = search_dict(jmespath.compile(expression), workflow.as_data, {})
+    print(f"Type: {type(rv)}")
+    pprint(rv)
+
+
+def main():
+    """Play around."""
+    for path in sorted(Path("docs/ideas/yaml").glob("*.toml")):
+        click.secho(str(path), fg="green")
+
+        toml_format = TOMLFormat(path=path)
+        config: dict = toml_format.as_data[".github/workflows/python.yaml"]
+
+        # config.pop("contains")
+        # config.pop("contains_sorted")
+
+        click.secho("JSON", fg="yellow")
+        print(json.dumps(config, indent=2))
+
+        click.secho("Flattened JSON", fg="yellow")
+        print(json.dumps(flatten(config), indent=2))
+
+    # find("jobs.build")
+    # find("jobs.build.strategy.matrix")
+    # find('jobs.build.strategy.matrix."python-version"')
+    # find("jobs.build.strategy.matrix.os")
+    # find("jobs.build.steps[]")
+    # find("jobs.build.steps[0]")
+    # find("jobs.build.steps[1]")
+    # find('jobs.build."runs-on"')
+    # find("jobs.build.steps[].name")
+    # find("jobs.build.steps[].uses")
+    # find("jobs.build.steps[].[name, uses]")
+    # find("jobs.build.steps[].{name: name, uses: uses}")
+
+
+if __name__ == "__main__":
+    main()

docs/ideas/yaml/contains.toml

@@ -0,0 +1,63 @@
+# 1. Same effect as items 1, 2 and 3 on "jmespath-on-section.toml", but with a different syntax.
+# 2. Everything that is not a dunder key ("__") will be a dict to be enforced.
+[[".github/workflows/python.yaml".contains]]
+__jmespath = "jobs.build.strategy.matrix"
+os = ["ubuntu-latest", "macos-latest", "windows-latest"]
+"python-version" = ["3.6", "3.7", "3.8", "3.9"]
+
+# 3. Same as item 4 on "jmespath-on-section.toml", but with a different syntax.
+[[".github/workflows/python.yaml".contains]]
+__jmespath = "jobs.build"
+"runs-on" = "${{ matrix.os }}"
+
+# 4. "jobs.build.steps" can have multiple dicts; each one is a "contains" table
+[[".github/workflows/python.yaml".contains]]
+__jmespath = "jobs.build.steps"
+uses = "actions/checkout@v2"
+
+# 5. The "problem" with the "contains" table is that "__jmespath" will be repeated many times
+[[".github/workflows/python.yaml".contains]]
+__jmespath = "jobs.build.steps"
+name = "Set up Python ${{ matrix.python-version }}"
+uses = "actions/setup-python@v2"
+with = {"python-version" = "${{ matrix.python-version }}"}
+
+# 6. Alternative to 5 with a multiline YAML string
+[[".github/workflows/python.yaml".contains]]
+__jmespath = "jobs.build.steps"
+__yaml = """
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v2
+        with:
+          python-version: ${{ matrix.python-version }}
+"""
+
+# 7. Alternative to 6, YAML without the whitespace.
+# Check if this is possible.
+# It would be best to ignored the initial whitespace and add the parsed data
+# directly under the "__jmespath"
+[[".github/workflows/python.yaml".contains]]
+__jmespath = "jobs.build.steps"
+__yaml = """
+- name: Set up Python ${{ matrix.python-version }}
+  uses: actions/setup-python@v2
+  with:
+    python-version: ${{ matrix.python-version }}
+"""
+
+# 8. Alternative to 4, but with formatted YAML in a single line string.
+[[".github/workflows/python.yaml".contains]]
+__jmespath = "jobs.build.steps"
+__yaml = "- uses: actions/checkout@v2"
+
+# 9. Same as items 1, 2 and 3, but asserting that they are ordered
+# in the sequence they appear here on the TOML file.
+# "contains_sorted" is an idea for a distant future, taken from text.toml, still not implemented
+[[".github/workflows/python.yaml".contains_sorted]]
+__jmespath = "jobs.build.strategy.matrix"
+os = ["ubuntu-latest", "macos-latest", "windows-latest"]
+"python-version" = ["3.6", "3.7", "3.8", "3.9"]
+
+[[".github/workflows/python.yaml".contains_sorted]]
+__jmespath = "jobs.build"
+"runs-on" = "${{ matrix.os }}"

docs/ideas/yaml/formatted-yaml.toml

@@ -0,0 +1,20 @@
+# Multiline YAML string
+[".github/workflows/python.yaml".jobs.build.steps]
+__yaml = """
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v2
+        with:
+          python-version: ${{ matrix.python-version }}
+"""
+
+# Alternative to the above YAML without the whitespace.
+# Check if this is possible.
+# It would be best to ignored the initial whitespace and add the parsed data
+# directly under the "__jmespath"
+[".github/workflows/python.yaml".jobs.build.steps.alternative]
+__yaml = """
+- name: Set up Python ${{ matrix.python-version }}
+  uses: actions/setup-python@v2
+  with:
+    python-version: ${{ matrix.python-version }}
+"""

docs/ideas/yaml/jmespath-on-section.toml

@@ -0,0 +1,25 @@
+# The values below were taken from .github/workflows/python.yaml in this repo
+
+# 1. JMESPath as part of the section name, after the file name.
+# Everything after the file name is considered a JMESPath https://jmespath.org/
+# Format: ["path/to/file.ext".jmes.path.expression]
+#
+# 2. "jobs.build.strategy.matrix" should have "os" and "python-version"
+# 3. Both are lists, and they have to be exactly as described here.
+[".github/workflows/python.yaml".jobs.build.strategy.matrix]
+os = ["ubuntu-latest", "macos-latest", "windows-latest"]
+"python-version" = ["3.6", "3.7", "3.8", "3.9"]
+
+# 4. "jobs.build" should have "runs-on" with value "${{ matrix.os }}"
+[".github/workflows/python.yaml".jobs.build]
+"runs-on" = "${{ matrix.os }}"
+
+# 5. "{{" and "}}" will conflict with Jinja https://github.com/andreoliwa/nitpick/issues/283
+# So we need a way to turn on/off Jinja templating.
+# Probably "false" will be the default, to keep compatibility.
+# Whoever wants to use Jinja will need to set "true" either here or as a global config on .nitpick.toml
+__jinja = false
+
+# 6. Another way to turn off Jinja for a specific key only, not the whole dict
+# (using the "__" syntax from Django filters, SQLAlchemy, factoryboy...)
+"runs-on__no_jinja" = "${{ matrix.os }}"

docs/ideas/yaml/jmespath-simple.toml

@@ -0,0 +1,7 @@
+# Simplified API, having JMESPath as direct keys
+# Read the discussion: https://github.com/andreoliwa/nitpick/pull/353/files#r613816390
+[".github/workflows/python.yaml"]
+"jobs.build.strategy.matrix.os" = "foo"
+"jobs.build.steps" = ["bar"]
+"jobs.build.steps.regex" = "baz d+"
+"jobs.build.steps.contains" = "baz"

docs/ideas/yaml/jmespath-table.toml

@@ -0,0 +1,25 @@
+# 1. Clean approach with JMESPath in tables and no reserved keys (`jmespath` or `__jmespath`)
+# https://github.com/andreoliwa/nitpick/pull/353/files#r614633283
+[[".github/workflows/python.yaml".jobs.build.steps]]
+uses = "actions/checkout@v2"
+
+[[".github/workflows/python.yaml".jobs.build.steps]]
+name = "Set up Python ${{ matrix.python-version }}"
+uses = "actions/setup-python@v2"
+with = {"python-version" = "${{ matrix.python-version }}"}
+
+# 2. Complex JMESPath expressions should be quoted
+# (I still don't know how to deal with JMESPath that matches multiple items)
+[[".github/workflows/python.yaml"."jobs.build.steps[].{name: name, uses: uses}"]]
+uses = "actions/checkout@v2"
+
+# 3. JMESPath expression that has double quotes, wrapped in single quotes for TOML
+[[".github/workflows/python.yaml".'jobs.build.strategy.matrix."python-version"']]
+name = "Set up Python ${{ matrix.python-version }}"
+uses = "actions/setup-python@v2"
+with = {"python-version" = "${{ matrix.python-version }}"}
+
+# 4. And it allows Jinja tuning in https://github.com/andreoliwa/nitpick/issues/283
+name__jinja = "Set up Python ${{ matrix.python-version }}"
+name__no_jinja = "Set up Python ${{ matrix.python-version }}"
+name__jinja_off = "Set up Python ${{ matrix.python-version }}"

tasks.py

@@ -234,7 +234,13 @@ def reactions(ctx):
             print(COLOR_NONE)
 
 
-namespace = Collection(install, update, test, pre_commit, doc, ci_build, lint, clean, reactions)
+@task
+def lab(ctx):
+    """Laboratory of ideas."""
+    ctx.run("poetry run python docs/ideas/lab.py")
+
+
+namespace = Collection(install, update, test, pre_commit, doc, ci_build, lint, clean, reactions, lab)
 namespace.configure(
     {
         "run": {