Document all the Python things #491

mdboom · 2019-11-19T12:29:26Z

@hackebrot: Everything documented here should be working (including the PyPI package). I'd appreciate your feedback on this PR as a user especially.

codecov-io · 2019-11-19T12:42:17Z

Codecov Report

Merging #491 into master will decrease coverage by <.01%.
The diff coverage is n/a.

@@             Coverage Diff              @@
##             master     #491      +/-   ##
============================================
- Coverage     76.55%   76.54%   -0.01%     
  Complexity      332      332              
============================================
  Files            96       96              
  Lines          5604     5603       -1     
  Branches        650      650              
============================================
- Hits           4290     4289       -1     
  Misses          832      832              
  Partials        482      482

Impacted Files	Coverage Δ	Complexity Δ
glean-core/src/common_metric_data.rs	`57.44% <0%> (-0.89%)`	`0% <0%> (ø)`

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update eed1ea0...a1853d0. Read the comment docs.

docs/user/adding-glean-to-your-project.md

docs/user/pings/baseline.md

docs/user/pings/events.md

docs/user/pings/metrics.md

hackebrot

Great work @mdboom! I added a few comments with feedback. 🚀

docs/user/adding-glean-to-your-project.md

hackebrot · 2019-11-19T14:18:21Z

docs/user/adding-glean-to-your-project.md

 The format of that file is documented [with `glean_parser`](https://mozilla.github.io/glean_parser/metrics-yaml.html).
 To learn more, see [adding new metrics](adding-new-metrics.md).

 > **Important**: as stated [before](adding-glean-to-your-project.md#before-using-glean), any new data collection requires documentation and data-review.
 > This is also required for any new metric automatically collected by the Glean SDK.

+{{#include ../tab_header.md}}
+
+<div data-lang="Swift" class="tab">


In this related to the Python bindings?

No, I just noticed reading through this that there was a note in the general section that pertained only to iOS, so I moved it to an iOS-specific section (and then added Python-specific content below it).

hackebrot · 2019-11-19T14:21:05Z

docs/user/adding-glean-to-your-project.md

+# if there are any metrics queued up from a previous run.
+Glean.set_upload_enabled(True)
+
+Glean.initialize(


What do you think of making the argument keyword argument only to be extra explicit?

That's a great idea. I filed a follow-on bug for that -- just to keep this one more-or-less docs only.

docs/user/adding-glean-to-your-project.md

docs/user/experiments-api.md

hackebrot · 2019-11-19T14:30:09Z

docs/user/testing-metrics.md

+
+It is generally a good practice to "reset" Glean prior to every unit test that uses Glean, to prevent side effects of one unit test impacting others.
+Glean contains a helper function `glean.testing.reset_glean()` for this purpose.
+It has two required arguments: the application id, and the application version.


Suggested change

It has two required arguments: the application id, and the application version.

It has two required arguments: the application ID, and the application version.

hackebrot · 2019-11-19T14:31:05Z

docs/user/testing-metrics.md

+Each reset of Glean will create a new temporary directory for Glean to store its data in.
+This temporary directory is automatically cleaned up the next time Glean is reset or when the testing framework finishes.
+
+The instructions below assume using `py.test` as the test runner.


Suggested change

The instructions below assume using `py.test` as the test runner.

The instructions below assume using [pytest](https://pypi.org/project/pytest/) as the test runner.

hackebrot · 2019-11-19T14:31:13Z

docs/user/testing-metrics.md

+The instructions below assume using `py.test` as the test runner.
+Other test-running libraries have similar features, but are different in the details.
+
+To have this function run before every unit test in a `py.test` module:


Suggested change

To have this function run before every unit test in a `py.test` module:

To have this function run before every unit test in a `pytest` module:

hackebrot · 2019-11-19T14:34:07Z

docs/user/testing-metrics.md

+```python
+from glean import testing
+
+def pytest_runtest_module():


I'm not familiar with this API and can't find anything in the pytest source or documentation.

Sorry -- this is a typo on my end. It's pytest_runtest_setup. And I'll add a link to the pytest docs here.

docs/user/testing-metrics.md

mdboom · 2019-11-19T15:45:22Z

docs/user/adding-glean-to-your-project.md

@@ -111,18 +111,73 @@ github "mozilla/glean" "master"

 </div>

+<div data-lang="Python" class="tab">
+
+It is recommended that you use a virtual environment for your work to isolate the dependencies for your project. There are many popular abstractions on top of virtual environments in the Python ecosystem which should help manage your project dependencies.


@hackebrot : Curious what you think of this. I don't want to write a tutorial on virtual environments (and all the related tools) here -- but should we recommend anything in particular?

I don't think we need to explain how to install packages, but if you want to add a recommendation for installing Glean, I would link to https://packaging.python.org/tutorials/installing-packages/ for more information.

Dexterp37 · 2019-11-20T09:16:17Z

Android tests failures are unrelated: I filed this bug.

hackebrot

Great work @mdboom! LGTM! 📝

I added one suggestion for the pytest fixture name.

docs/user/testing-metrics.md

Co-Authored-By: Raphael Pierzina <raphael@hackebrot.de>

mdboom requested review from badboy, Dexterp37 and travis79 as code owners November 19, 2019 12:29

Dexterp37 requested changes Nov 19, 2019

View reviewed changes

docs/user/adding-glean-to-your-project.md Show resolved Hide resolved

docs/user/pings/baseline.md Outdated Show resolved Hide resolved

docs/user/pings/events.md Outdated Show resolved Hide resolved

docs/user/pings/metrics.md Outdated Show resolved Hide resolved

hackebrot suggested changes Nov 19, 2019

View reviewed changes

mdboom commented Nov 19, 2019

View reviewed changes

mdboom requested review from Dexterp37 and hackebrot November 19, 2019 16:20

Dexterp37 approved these changes Nov 19, 2019

View reviewed changes

mdboom added 7 commits November 19, 2019 12:35

Document all the Python things

269586c

Address low-hanging fruit comments in the PR

472c95c

Update test fixture instructions

6b7a5d5

Clarify events ping

590d6c7

Typo

cb8eb31

Fix typo

3fd7e68

Add link to other docs.

24c1a96

mdboom force-pushed the python-docs branch from 531157e to 24c1a96 Compare November 19, 2019 22:44

Add note about Python data directory

a8158ae

Dexterp37 approved these changes Nov 20, 2019

View reviewed changes

hackebrot approved these changes Nov 20, 2019

View reviewed changes

docs/user/testing-metrics.md Outdated Show resolved Hide resolved

Update docs/user/testing-metrics.md

a1853d0

Co-Authored-By: Raphael Pierzina <raphael@hackebrot.de>

mdboom merged commit 8b511a3 into mozilla:master Nov 20, 2019

mdboom deleted the python-docs branch April 14, 2020 19:09

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Document all the Python things #491

Document all the Python things #491

mdboom commented Nov 19, 2019 •

edited

codecov-io commented Nov 19, 2019 •

edited

hackebrot left a comment

hackebrot Nov 19, 2019

mdboom Nov 19, 2019

hackebrot Nov 19, 2019

mdboom Nov 19, 2019

hackebrot Nov 19, 2019

hackebrot Nov 19, 2019

hackebrot Nov 19, 2019

hackebrot Nov 19, 2019

mdboom Nov 19, 2019

mdboom Nov 19, 2019

hackebrot Nov 19, 2019

Dexterp37 commented Nov 20, 2019

hackebrot left a comment

	It has two required arguments: the application id, and the application version.
	It has two required arguments: the application ID, and the application version.

	The instructions below assume using `py.test` as the test runner.
	The instructions below assume using [pytest](https://pypi.org/project/pytest/) as the test runner.

	To have this function run before every unit test in a `py.test` module:
	To have this function run before every unit test in a `pytest` module:

Document all the Python things #491

Document all the Python things #491

Conversation

mdboom commented Nov 19, 2019 • edited

codecov-io commented Nov 19, 2019 • edited

Codecov Report

hackebrot left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Dexterp37 commented Nov 20, 2019

hackebrot left a comment

Choose a reason for hiding this comment

mdboom commented Nov 19, 2019 •

edited

codecov-io commented Nov 19, 2019 •

edited