1# Python SPDX Library to parse, validate and create SPDX documents 2 3| Linux | macOS | Windows | 4| :---- | :------ | :---- | 5[ ![Linux build status][1]][2] | [![macOS build status][3]][4] | [![Windows build status][5]][6] | 6 7[1]: https://travis-ci.org/spdx/tools-python.svg?branch=master 8[2]: https://travis-ci.org/spdx/tools-python 9[3]: https://circleci.com/gh/spdx/tools-python/tree/master.svg?style=shield&circle-token=36cca2dfa3639886fc34e22d92495a6773bdae6d 10[4]: https://circleci.com/gh/spdx/tools-python/tree/master 11[5]: https://ci.appveyor.com/api/projects/status/0bf9glha2yg9x8ef/branch/master?svg=true 12[6]: https://ci.appveyor.com/project/spdx/tools-python/branch/master 13 14This library implements an SPDX tag/value and RDF parser, validator and handler in Python. 15This is the result of an initial GSoC contribution by @[ah450](https://github.com/ah450) (or https://github.com/a-h-i) and 16is maintained by a community of SPDX adopters and enthusiasts. 17 18Home: https://github.com/spdx/tools-python 19 20Issues: https://github.com/spdx/tools-python/issues 21 22Pypi: https://pypi.python.org/pypi/spdx-tools 23 24 25# License 26 27[Apache-2.0](LICENSE) 28 29 30# Features 31 32* API to create and manipulate SPDX documents. 33* Parse and create Tag/Value, RDF, JSON, YAML, XML format SPDX files 34 35 36# TODOs 37 38* Update to full SPDX v2.1 39* Add to full license expression support 40 41 42# How to use 43 44Example tag/value parsing usage: 45```Python 46 from spdx.parsers.tagvalue import Parser 47 from spdx.parsers.tagvaluebuilders import Builder 48 from spdx.parsers.loggers import StandardLogger 49 p = Parser(Builder(), StandardLogger()) 50 p.build() 51 # data is a string containing the SPDX file. 52 document, error = p.parse(data) 53 54``` 55 56The `examples` directory contains several code samples. Here some of them: 57 58* `parse_tv.py` is an example tag/value parsing usage. 59 Try running `python parse_tv.py ../data/SPDXSimpleTag.tag ` 60 61* `write_tv.py` provides an example of writing tag/value files. 62 Run `python write_tv.py sample.tag` to test it. 63 64* `pp_tv.py` demonstrates how to pretty-print a tag/value file. 65 To test it run `python pp_tv.py ../data/SPDXTagExample.tag pretty.tag`. 66 67* `parse_rdf.py` demonstrates how to parse an RDF file and print out document 68 information. To test it run `python parse_rdf.py ../data/SPDXRdfExample.rdf` 69 70* `rdf_to_tv.py` demonstrates how to convert an RDF file to a tag/value one. 71 To test it run `python rdf_to_tv.py ../data/SPDXRdfExample.rdf converted.tag` 72 73* `pp_rdf.py` demonstrates how to pretty-print an RDF file, to test it run 74 `python pp_rdf.py ../data/SPDXRdfExample.rdf pretty.rdf` 75 76 77# Installation 78 79As always you should work in a virtualenv or venv. You can install a local clone 80of this repo with `yourenv/bin/pip install .` or install from PyPI with 81`yourenv/bin/pip install spdx-tools`. Note that on Windows it would be `Scripts` 82instead of `bin`. 83 84 85# How to run tests 86 87From the project root directory run: `python setup.py test`. 88You can use another test runner such as pytest or nose at your preference. 89 90 91# Development process 92 93We use the GitHub flow that is described here: https://guides.github.com/introduction/flow/ 94 95So, whenever we have to make some changes to the code, we should follow these steps: 961. Create a new branch: 97 `git checkout -b fix-or-improve-something` 982. Make some changes and the first commit(s) to the branch: 99 `git commit -m 'What changes we did'` 1003. Push the branch to GitHub: 101 `git push origin fix-or-improve-something` 1024. Make a pull request on GitHub. 1035. Continue making more changes and commits on the branch, with `git commit` and `git push`. 1046. When done, write a comment on the PR asking for a code review. 1057. Some other developer will review your changes and accept your PR. The merge should be done with `rebase`, if possible, or with `squash`. 1068. The temporary branch on GitHub should be deleted (there is a button for deleting it). 1079. Delete the local branch as well: 108 ``` 109 git checkout master 110 git pull -p 111 git branch -a 112 git branch -d fix-or-improve-something 113 ``` 114 115Besides this, another requirement is that every change should be made to fix or close an issue: https://guides.github.com/features/issues/ 116If there is no issue for the changes that you want to make, create first an issue about it that describes what needs to be done, assign it to yourself, and then start working for closing it. 117 118 119# Dependencies 120 121* PLY : https://pypi.python.org/pypi/ply/ used for parsing. 122* rdflib : https://pypi.python.org/pypi/rdflib/ for handling RDF. 123* PyYAML: https://pypi.org/project/PyYAML/ for handling YAML. 124* xmltodict: https://pypi.org/project/xmltodict/ for handling XML. 125 126 127# Support 128 129* Submit issues, questions or feedback at: https://github.com/spdx/tools-python/issues 130* Join the dicussion on https://lists.spdx.org/mailman/listinfo/spdx-tech and 131 https://spdx.org/WorkgroupTechnical 132