ab53f99d3a1eab8dca74b19538eb390ac8c6e8c2
[nm/python-debiancontributors.git] / README.md
1 debiancontributors python module
2 ================================
3
4 See https://wiki.debian.org/DebianContributors for technical information about
5 contributors.debian.org
6
7 See https://wiki.debian.org/Teams/FrontDesk/DcSiteDevel for this project's page
8 in the Debian wiki.
9
10 ## Computing and posting data using dc-tool
11
12 You can describe a data source and how to look for contribution data in a
13 simple configuration file, then run this to perform data mining and submit data
14 to the site, all in one go:
15
16         dc-tool --mine myconfigfile --post
17
18 Without --post, it prints the results of data mining on standard output: it is
19 useful to test a data mining configuration.
20
21 See DATAMINING.rst and the examples/ directory for documentation and examples
22 for the data mining configuration.
23
24 ## Posting data using dc-tool
25
26 Assuming you [created a data source in the website][newds] called
27 `myteam.debian.net` with authentication token 'foobar'.
28
29 Assuming you have generated a file `submission.json`, with your submission.
30
31 You can post it with `dc-tool` using:
32
33         dc-tool --source myteam.debian.net --auth-token foobar --post submission.json
34
35 dc-tool will validate the submission for you before posting it.
36
37 You can check the contents of the submission by running `dc-tool` without
38 any option:
39
40         dc-tool submission.json
41
42 ## Posting data using python code
43
44 Assuming you [created a data source in the website][newds] called
45 `myteam.debian.net` with authentication token 'foobar'.
46
47         import debiancontributors as dc
48         from datetime import Date
49
50         # Create a Submission
51         s = dc.Submission("myteam.debian.net")
52
53         # Add contribution data to it
54         s.add_contribution(
55                 dc.Identifier("email", "enrico@debian.org"),
56                 dc.Contribution("shave_yaks", Date(2013, 1, 1), Date(2013, 12, 23)))
57
58         # Post it to the site
59         success, info = s.post("foobar")
60         if not success:
61                 import json
62                 print("submission failed:")
63                 print(json.dumps(info, indent=1))
64
65
66 ## Posting data the way you like
67
68 Posting a submission is just a matter of building a JSON data structure and
69 posting it to the site via HTTP POST. See
70 [DebianContributors Implementation notes](https://wiki.debian.org/DebianContributors#Implementation_notes)
71 for details.
72
73 [newds]: https://wiki.debian.org/DebianContributors#Creating_a_new_data_source