File: README.rst

package info (click to toggle)
usagestats 0.5-1
  • links: PTS
  • area: main
  • in suites: stretch
  • size: 172 kB
  • ctags: 73
  • sloc: python: 555; sh: 60; makefile: 17
file content (82 lines) | stat: -rw-r--r-- 2,895 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
Usage statistics collector
==========================

This package is meant to easily get usage statistics from the users of your
program.

Statistics will be collected but won't be uploaded until the user opts in. A
message will be printed on stderr asking the user to explicitely opt in or opt
out.

Usage
-----

You can easily collect information from your program by adding usagestats to
your project's requirements and using the library. Here is an example::

    import usagestats
    import sys


    optin_prompt = usagestats.Prompt(enable='cool_program --enable-stats',
                                     disable='cool_program --disable-stats')

    # Location where to store stats
    # Also allocates a unique ID for the user
    # The version is important, since the information you log (or the format)
    # might change in later versions of your program
    stats = usagestats.Stats('~/.myprog/usage_stats',
                             optin_prompt,
                             'https://usagestats.example.org/',
                             unique_user_id=True,
                             version='0.1')


    def main():
        if len(sys.argv) < 2:
            pass
        elif sys.argv.get(1) == '--enable-stats':
            stats.enable_reporting()
            sys.exit(0)
        elif sys.argv.get(1) == '--disable-stats':
            stats.disable_reporting()
            sys.exit(0)

        if sys.version_info < (3,):
            # Stores some info, will be reported when submit() is called
            stats.note({'mode': 'compatibility'})

        # Report things
        stats.submit(
            # Dictionary containing the info
            {'what': 'Ran the program'},
            # Flags making usagestats insert more details
            usagestats.OPERATING_SYSTEM,  # Operating system/distribution
            usagestats.PYTHON_VERSION,    # Python version info
            usagestats.SESSION_TIME,      # Time since Stats object was created
        )


    if __name__ == '__main__':
        main()

`submit()` will, by default, store the info in the specified directory. Nothing
will be reported until the user opts in; a message will simply be printed to
stderr::

    Uploading usage statistics is currently DISABLED
    Please help us by providing anonymous usage statistics; you can enable this
    by running:
        cool_program --enable-stats
    If you do not want to see this message again, you can run:
        cool_program --disable-stats
    Nothing will be uploaded before you opt in.

Server
------

To collect the reports, any server will do; the reports are uploaded via POST
as a LF-separated list of ``key:value`` pairs. A simple script for mod_wsgi is
included; it writes each report to a separate file. Writing your own
implementation in your language of choice (PHP, Java) with your own backend
should be fairly straightforward.