Moved tools to .tools from .doc_gen and added README with Python proj…

…ect rules.

.flake8

@@ -0,0 +1,4 @@
+# In the root for editors when opening the workspace as a whole.
+[flake8]
+extend-ignore = E203,E501
+exclude = .git,__pycache__,

.tools/.flake8

@@ -0,0 +1,5 @@
+[flake8]
+extend-ignore = E203,E501
+exclude =
+    .git,
+    __pycache__,

.tools/README.md

@@ -0,0 +1,84 @@
+# SDK Code Examples Tools
+
+These tools help SDK Code Example developers' integration with internal docs tooling.
+This is mainly in the form of .doc_gen SOS metadata validation, with other tools as necessary.
+
+SDK Code Examples tools team uses Python for our tools because of its cross-platform runtime and broad knowledge base.
+
+## Tooling Guidelines
+
+1. Use Python latest for tooling (this is not the same rule as for python sdk, be aware).
+2. Our “standard library” adds `flake8`, `black`, `pyyaml`, `yamale`, and `requests`
+   - Current versions are in base_requirements.txt
+3. Run `.tools/verify_python.py` to ensure python tools is configured as expected.
+   - This will install our “standard library” to site_packages and ensure that the python version is at least 3.(current - 1).
+4. Use a venv in `.venv` if the project needs packages beyond our standard library.
+   1. Include those libraries in the `requirements.txt`.
+   2. Copy `.tools/base-requirements.txt` to the tool’s folder to seed `requirements.txt` if you like
+   3. With an active venv, run `pip freeze > requirements.txt` to update the tool’s requirements.
+5. Keep tools self executable
+   1. Mark them executable (`chmod a+x <script.py>` in \*nix)
+   2. Add a shebang `#!/usr/bin/env python3`
+   3. Use `__name__ == “__main__”` check that delegates to a `main` function
+6. Use f-strings for string building.
+7. Use `logging` to write diagnostics to the console.
+8. Format using Black with default settings.
+9. Lint using `flake8` and default settings.
+   - Treat Warnings as errors
+   - Except line length E501, because it disagrees with black
+10. Verify type annotations using mypy.
+    - Type annotations are strongly recommended.
+11. Run tests using pytest.
+12. Parse arguments using argparse.
+    - All scripts must run headless, without user interaction.
+13. Use pathlib for files and paths.
+    - Prefer os.scandir to os.listdir.
+14. Parse & dump yaml using PyYAML. (imports from `yaml`)
+    - Validate yaml schemas using `yamale`
+15. When working with dates, import from datetime and always include a timezone (usually `timezone.utc`).
+16. Prefer data classes or immutable tuples for base data types.
+17. Use requests for web calls, but prefer a native wrapper (like boto3 or pygithub) when available.
+    - If you http/2, you might consider httpx
+18. Use subprocess for system calls, but prefer a native wrapper (like gitpython) when available.
+
+## Some PEPs you might want to know about:
+
+Python 3.12:
+
+- [PEP 701](http://www.python.org/dev/peps/pep-0701) -- More flexible f-string parsing
+- [PEP 695](http://www.python.org/dev/peps/pep-0695) -- New type annotations syntax for generic classes
+
+Python 3.11:
+
+- [PEP 654](http://www.python.org/dev/peps/pep-0654) -- Exception Groups and except\*
+
+Python 3.10:
+
+- [PEP 604](http://www.python.org/dev/peps/pep-0604) -- Allow writing union types as X | Y
+- [PEP 636](http://www.python.org/dev/peps/pep-0636) -- Structural Pattern Matching: Tutorial
+
+Python 3.9:
+
+- [PEP 585](http://www.python.org/dev/peps/pep-0585), Type Hinting Generics In Standard Collections
+- [PEP 602](http://www.python.org/dev/peps/pep-0602), Python adopts a stable annual release cadence
+
+Python 3.8
+
+- [PEP 572](http://www.python.org/dev/peps/pep-0572), Assignment expressions
+- [PEP 586](http://www.python.org/dev/peps/pep-0586), Literal types
+- [PEP 589](http://www.python.org/dev/peps/pep-0589), TypedDict
+
+Python 3.7
+
+- [PEP 557](http://www.python.org/dev/peps/pep-0557), Data Classes
+
+## VSCode Extensions
+
+- https://marketplace.visualstudio.com/items?itemName=ms-python.mypy-type-checker
+- https://marketplace.visualstudio.com/items?itemName=ms-python.flake8
+- https://marketplace.visualstudio.com/items?itemName=ms-python.black-formatter
+
+## Flake8 Ignore
+
+- E203 whitespace before ':'
+- E501 line too long

.tools/base_requirements.txt

@@ -0,0 +1,18 @@
+black==23.9.1
+certifi==2023.7.22
+charset-normalizer==3.3.0
+click==8.1.7
+flake8==6.1.0
+idna==3.4
+mccabe==0.7.0
+mypy-extensions==1.0.0
+packaging==23.2
+pathspec==0.11.2
+platformdirs==3.11.0
+pycodestyle==2.11.1
+pyflakes==3.1.0
+PyYAML==6.0.1
+requests==2.31.0
+types-PyYAML==6.0.12.12
+urllib3==2.0.6
+yamale==4.0.4

.tools/images/render-blurbs.py

@@ -0,0 +1,22 @@
+import os
+
+import jinja2
+import yaml
+from pathlib import Path
+
+env = jinja2.Environment(
+    loader=jinja2.FileSystemLoader(os.path.dirname(__file__)),
+    autoescape=jinja2.select_autoescape(
+        enabled_extensions=("html", "xml"), default_for_string=True
+    ),
+)
+
+if __name__ == "__main__":
+    sdk_metadata = Path(__file__).parent / ".." / ".." / "metadata" / "sdks.yaml"
+    with open(sdk_metadata, "r") as file:
+        metadata = yaml.safe_load(file)
+        for language in metadata.keys():
+            metadata[language]
+            shortname = metadata[language]["property"]
+            template = env.get_template("template.txt")
+            print(template.render(language=language, shortname=shortname))

.tools/validation/.flake8

@@ -0,0 +1,5 @@
+[flake8]
+extend-ignore = E203,E501
+exclude =
+    .git,
+    __pycache__,