{ "info": { "author": "Rett Berg", "author_email": "googberg@gmail.com", "bugtrack_url": null, "classifiers": [ "Development Status :: 3 - Alpha", "Intended Audience :: Developers", "License :: OSI Approved :: MIT License", "Operating System :: Microsoft :: Windows", "Operating System :: POSIX", "Operating System :: Unix", "Programming Language :: Python", "Programming Language :: Python :: 2.7", "Programming Language :: Python :: 3", "Programming Language :: Python :: 3.4", "Programming Language :: Python :: 3.5", "Programming Language :: Python :: 3.6", "Programming Language :: Python :: 3.7", "Programming Language :: Python :: Implementation :: CPython", "Programming Language :: Python :: Implementation :: PyPy", "Topic :: Utilities" ], "description": "# Artifact-py: a reimagining of [artifact]\n> NOTICE: this is in alpha. It works but likely has many bugs and missing\n> features.\n\nThis is a reimplementation of [artifact] in python. It will be the barebones of\nartifact necessary to put it in a build system. No featureful cli, no web-ui.\nJust parsing and exporting of json/markdown/etc.\n\nAt the same time, this is not a strict rewrite. It is a reimagining and will\nprobably guide the development of artifact 3.0.\n\nInstall with `pip install artifact_py`. It should work in python 2.7+ and 3+\n\n## Differences with [artifact]\n\nThe primary differences will be:\n- Written in python instead of rust for easier inclusion in legacy build\n systems.\n- The use of the new [anchor_txt] markdown attribute format, developed\n specifically for this project to not have dependencies on any specific\n markdown implementation.\n- Removal of `.art/settings.toml`, replaced with an attribute block anywhere in\n the markdown file.\n- Massive simplification of the cmdline tool. The CLI may be improved in the future.\n- A few minor tweaks to simplify how artifacts are specified and linked.\n - Markdown can be exported _in place_ -- almost none of the document has to\n be changed.\n - Artifacts are now specified by the anchor in a header. Conventionally it\n will look like `# This is my spec (SPC-mine) {#SPC-mine}`. The\n `{#SPC-mine}` is a (not-quite) standard markdown anchor used to create a\n reference. The `(SPC-mine)` is by-convention so that humans can see that\n the header is specifying an artifact.\n - Note: `anchor_txt` also supported the html anchor ``,\n which is what is necessary in github\n - Artifact attributes are specified with a fenced code block. See [SPC-design]\n for an example.\n - Removal of `[[REQ-foo]]` references. Instead you just use `[REQ-foo]` or `[@REQ-foo]` for code.\n When you run `art export --format md -i` they will strip out references that look like\n `ART-foo.bar` and insert the correct links at the bottom of your document.\n (i.e. `[@REQ-foo]: url/to/code.py`\n - Removal of specifying subparts (formerly called subnames) via\n `[[REQ-foo.subpart]]`. Simply specify them in your attributes with partof,\n and link to the code in your deisign doc with `[@REQ-foo.subpart]`.\n - Has no special support for graphviz.\n - No exporting of the relationship of artifacts to the markdown file itself.\n In the author's opinion this frequently just added to clutter and was not\n especially useful.\n\nOverall, this design works much more hand-in-hand with the standard markdown\nspecification. It _feels_ cleaner, and allows for easier conversion from an\n\"arbitrary\" design document to one that is rich in links to source code and\nother designs.\n\nFeatures still to be added:\n- Currently only supports a single markdown file. I also want to re-imagine how large\n numbers of files/etc could be integrated before adding more files.\n- Linting -- no linter currently exists\n- `text` field in the json of artifact. It was not required for any implementation details\n and may be added later.\n- A stable json output format. It is still in flux.\n\n# Contributing\n\nSee [LICENSE](#license) for conditions of contributions.\n\nCode is in python. Test using the following:\n\n```\n# create the python virtualenv's locally\nmake init\n\n# run tests against python3\nmake test3\n\n# run all checks required to ship\nmake check\n```\n\n# Design (SPC-design) \n```yaml @\nsubparts:\n - artifact\n - settings\n - code\n - lint\n - tst-unittests\n```\n\nAll attributes and settings are specified with an [anchor_txt] code block.\n\nSettings are specified like this, anywhere in the document:\n\n ```yaml @\n artifact:\n root_dir: ./\n code_paths:\n - src/\n ```\n\nArtifact attributes like this:\n\n ```yaml @\n partof:\n - SPC-other\n\n subparts:\n - function\n - tst-unit\n ```\n\n## Settings (SPC-design.settings) \n> _code: [@SPC-design.settings]_\n\nArtifacts are injected from the `--doc` markdown design document. All\nsettings/attributes are provided using the [anchor_txt] format. Settings\nare provided by adding the following to an `artifact` attribute anywhere\nin the document:\n\n- `root_dir`: the root directory when creating paths. This will affect\n where other path settings use as a reference.\n- `code_paths`: paths to files or directories to look for code.\n See [Code Links](#SPC-design.code) for more information.\n- `exclude_code_paths`: paths to exclude when searching for artifacts.\n\n\n## Artifact (SPC-design.artifact) \n> _code: [@SPC-design.artifact]_\n\nAn artifact is a piece of documentation that can be linked to other pieces of\ndocumentation and to source code. It has the following attributes:\n\n- `name`: defines how it can be linked. The name is defined in the\n anchor header (`{#REQ-foo}`)\n - There are three types of artifacts: REQ (requirement), SPC (specification),\n TST (test)\n- `partof`: the other artifacts this artifact is a partof.\n- `subparts`: pieces of an artifact that can be linked in code.\n- `done`: force an artifact to be considered specified and tested\n\n\n## Code Links (SPC-design.code) \n> _code: [@SPC-design.code]_\n\nArtifacts are linked in code by:\n- Defining an artifact name or subpart\n- Specifying `code_paths` in [Settings](#SPC-design.settings)\n- Putting a tag anywhere in code of the form:\n - `#SPC-foo`\n - `#SPC-foo.bar`\n\nArtifact will run a regular expression over all files found in `code_paths` and\nwill mark artifacts as specified/tested if they are linked in code.\n\n## Lints (SPC-design.lint) \n> Note: This is not yet implemented\n>\n> _code: [@SPC-design.lint]_\n\nThe lint command will find errors in the design document, and how it is\nreflected in the code:\n\n- `partof` links that do not exist.\n- A `REQ` or `SPC` being `partof` a `TST`\n- Extra `impl` links in code\n- Having an artifact specified as \"done\" having an impl\n- Artifact or subpart like links in text (i.e. `[REQ-does-not-exist]`) that do\n not exist.\n- Design docs not being updated (run `artifact export --format md -i` to fix).\n- A link being found in code that does not have the `doc_url` prefixed.\n (i.e. artifact expects links in code to look like `myurl.com/design#REQ-foo`)\n\n## Multi-project designs (SPC-design.multi) \n> Not yet implemented, design phase only\n>\n> _code: [@SPC-design.multi]_\n\nArtifact's previous design fell short of supporting multiple different designs,\nespecially at scale. This rewrite/reimainging immagines the following principles:\n\n- Designs for a \"module/package/submodule/etc\" are contained within a single file.\n This links to a \"small\" amount of source code for that design and are specified\n in the `artifact` attribute in that file.\n- Linking to other design files can be done via a \"references\" object in the settings.\n They are specified like `other_design: path/to/other/file`\n- Inline links will then be auto-generated so that you can use\n `[other_design#SPC-foo]` to link to other documents.\n - Specified and tested ratios are not affected by these links.\n\nBecause the designs are only _linked_ together (not dependent on eachother for\ncompletion ratios), each design can be calculated independently and it's\nmetadata serialized so that other projects can link to it.\n\n\n## Unit Tests (SPC-design.tst-unittests) \n> _code: [@SPC-design.tst-unittests]_\n\nThe unit tests offer almost complete coverage. Nearly all of the features\nare tested using a data-driven approach. There is a markdown file, with\na yaml file of the same name. The yml file has the expected value after\nparsing the markdown file.\n\nAlso tested:\n- That exporting the project results in the expected markdown file\n\n\n# License\n\nThe source code is Licensed under either of\n\n* Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or\n http://www.apache.org/licenses/LICENSE-2.0)\n* MIT license ([LICENSE-MIT](LICENSE-MIT) or\n http://opensource.org/licenses/MIT)\n\nat your option.\n\nUnless you explicitly state otherwise, any contribution intentionally submitted\nfor inclusion in the work by you, as defined in the Apache-2.0 license, shall\nbe dual licensed as above, without any additional terms or conditions.\n\n\n# Metadata\n\n```yaml @\nartifact:\n root_dir: './'\n\n code_paths:\n - artifact_py/\n - tests/\n\n exclude_code_paths:\n - tests/artifacts_only/\n - tests/projects/\n - tests/test_code.py\n\n code_url:\n \"https://github.com/vitiral/artifact_py/blob/master/{file}#L{line}\"\n```\n\n[artifact]: https://github.com/vitiral/artifact\n[anchor_txt]: https://github.com/vitiral/anchor_txt\n\n[@SPC-design.artifact]: https://github.com/vitiral/artifact_py/blob/master/artifact_py/artifact.py#L29\n[@SPC-design.code]: https://github.com/vitiral/artifact_py/blob/master/artifact_py/code.py#L18\n[@SPC-design.settings]: https://github.com/vitiral/artifact_py/blob/master/artifact_py/settings.py#L30\n[@SPC-design.tst-unittests]: https://github.com/vitiral/artifact_py/blob/master/tests/__init__.py#L1\n[@SPC-design]: https://github.com/vitiral/artifact_py/blob/master/artifact_py/__init__.py#L21\n[SPC-design.artifact]: #SPC-design.artifact\n[SPC-design.code]: #SPC-design.code\n[SPC-design.lint]: #SPC-design.lint\n[SPC-design.settings]: #SPC-design.settings\n[SPC-design.tst-unittests]: #SPC-design.tst-unittests\n[SPC-design]: #SPC-design", "description_content_type": "text/markdown", "docs_url": null, "download_url": "", "downloads": { "last_day": -1, "last_month": -1, "last_week": -1 }, "home_page": "https://github.com/vitiral/artifact_py", "keywords": "", "license": "MIT or APACHE-2.0", "maintainer": "", "maintainer_email": "", "name": "artifact-py", "package_url": "https://pypi.org/project/artifact-py/", "platform": "", "project_url": "https://pypi.org/project/artifact-py/", "project_urls": { "Homepage": "https://github.com/vitiral/artifact_py", "Issue Tracker": "https://github.com/vitiral/artifact_py/issues" }, "release_url": "https://pypi.org/project/artifact-py/0.1.2/", "requires_dist": null, "requires_python": ">=2.7", "summary": "The design documentation tool for everyone", "version": "0.1.2" }, "last_serial": 5718690, "releases": { "0.1.0": [ { "comment_text": "", "digests": { "md5": "9425719e216dfec5ee00c14f74bd0614", "sha256": "a7e8a2ef8c9628450f01b1960d9593fb215cd33e77345128d45aeb8754f6f46b" }, "downloads": -1, "filename": "artifact_py-0.1.0.tar.gz", "has_sig": false, "md5_digest": "9425719e216dfec5ee00c14f74bd0614", "packagetype": "sdist", "python_version": "source", "requires_python": ">=2.7", "size": 16135, "upload_time": "2019-07-22T17:06:47", "url": "https://files.pythonhosted.org/packages/aa/14/a1005b1f5733da6dbe6294e030eb9c31cd5dd9565bec504604fc20ac0f1b/artifact_py-0.1.0.tar.gz" } ], "0.1.1": [ { "comment_text": "", "digests": { "md5": "01fc992fb5347dd4c179ab36b4cda584", "sha256": "fbf5984e5329215e86d5cd82065c24481acffb31d4bb93a2dfeb85e6d4427cc5" }, "downloads": -1, "filename": "artifact_py-0.1.1.tar.gz", "has_sig": false, "md5_digest": "01fc992fb5347dd4c179ab36b4cda584", "packagetype": "sdist", "python_version": "source", "requires_python": ">=2.7", "size": 16322, "upload_time": "2019-07-22T17:18:49", "url": "https://files.pythonhosted.org/packages/d1/06/3b9ec525faaf5eb38d40b8dee17e3deb1c3f33da1eb3742b0096bda1e472/artifact_py-0.1.1.tar.gz" } ], "0.1.2": [ { "comment_text": "", "digests": { "md5": "801b0b60190874d7d519de0881ee0d3b", "sha256": "6f63cfa01bb3d9d26d9937bc2062205bfb16c78176aaf3fcd8129eb6bb18c3c6" }, "downloads": -1, "filename": "artifact_py-0.1.2.tar.gz", "has_sig": false, "md5_digest": "801b0b60190874d7d519de0881ee0d3b", "packagetype": "sdist", "python_version": "source", "requires_python": ">=2.7", "size": 16887, "upload_time": "2019-08-23T03:57:54", "url": "https://files.pythonhosted.org/packages/2c/cd/214405237d58c66c84a68f95b6e20d923f9419f6441182fcd343df58941a/artifact_py-0.1.2.tar.gz" } ] }, "urls": [ { "comment_text": "", "digests": { "md5": "801b0b60190874d7d519de0881ee0d3b", "sha256": "6f63cfa01bb3d9d26d9937bc2062205bfb16c78176aaf3fcd8129eb6bb18c3c6" }, "downloads": -1, "filename": "artifact_py-0.1.2.tar.gz", "has_sig": false, "md5_digest": "801b0b60190874d7d519de0881ee0d3b", "packagetype": "sdist", "python_version": "source", "requires_python": ">=2.7", "size": 16887, "upload_time": "2019-08-23T03:57:54", "url": "https://files.pythonhosted.org/packages/2c/cd/214405237d58c66c84a68f95b6e20d923f9419f6441182fcd343df58941a/artifact_py-0.1.2.tar.gz" } ] }