Update user-facing functions docstring with examples (#258) by talgalili · Pull Request #259 · facebookresearch/balance

talgalili · 2026-01-12T11:56:15Z

Summary:

Resolves [FEATURE] Update the dosctring of all user-facing functions with 'examples' from the tests #192
Will update missing ones (if there are any) in seperate PR.

Differential Revision: D90492354

Pulled By: talgalili

meta-codesync · 2026-01-12T11:56:22Z

@talgalili has exported this pull request. If you are a Meta employee, you can view the originating Diff in D90492354.

Copilot

Pull request overview

This PR adds concrete usage examples to docstrings for user-facing functions across the balance package to improve documentation and help developers understand how to use the APIs. The PR also updates formatting from :: to .. code-block:: python for consistency and includes workflow file changes.

Changes:

Added docstring examples with expected outputs to 40+ user-facing functions across weighting methods (rake, ipw, cbps, adjust_null), statistics utilities (weighted_stats, weighted_comparisons_stats, general_stats), and core classes (Sample, BalanceDF)
Updated reStructuredText formatting from :: to .. code-block:: python for consistency across existing examples
Updated GitHub Actions workflow to use Python 3.12 and black 25.1.0 for linting

Reviewed changes

Copilot reviewed 13 out of 13 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
balance/weighting_methods/rake.py	Added example for `rake()` and updated formatting for helper functions (`_proportional_array_from_dict`, `_find_lcm_of_array_lengths`, `_realize_dicts_of_proportions`, `prepare_marginal_dist_for_raking`)
balance/weighting_methods/ipw.py	Added examples for `model_coefs()`, `link_transform()`, `calc_dev()`, `weights_from_link()`, and `choose_regularization()`
balance/weighting_methods/cbps.py	Added examples for `logit_truncated()`, `compute_pseudo_weights_from_logit_probs()`, `bal_loss()`, `gmm_function()`, `gmm_loss()`, `alpha_function()`, `compute_deff_from_beta()`, and `cbps()`
balance/weighting_methods/adjust_null.py	Added example for `adjust_null()`
balance/stats_and_plots/weighted_stats.py	Updated formatting and added examples for `weighted_var()`, `weighted_sd()`, and `weighted_quantile()`
balance/stats_and_plots/weighted_comparisons_stats.py	Updated formatting and added examples for `asmd_improvement()` and `outcome_variance_ratio()`
balance/stats_and_plots/general_stats.py	Rewrote example for `relative_response_rates()` with simpler, clearer demonstration
balance/sample_class.py	Added examples for 20+ methods including `from_frame()`, `df`, `outcomes()`, `weights()`, `covars()`, `ignored_columns()`, `model()`, `model_matrix()`, `set_weights()`, `set_unadjusted()`, `is_adjusted()`, `set_target()`, `has_target()`, `design_effect()`, `design_effect_prop()`, `outcome_sd_prop()`, `outcome_variance_ratio()`, `summary()`, `diagnostics()`, `keep_only_some_rows_columns()`, `to_download()`, `to_csv()`, and updated formatting for others
balance/csv_utils.py	Added example for `to_csv_with_defaults()`
balance/balancedf_class.py	Updated formatting and added examples for `to_download()`, `df`, `summary()`, `from_frame()`, `design_effect()`, `trim()`, and `to_csv()`
balance/adjustment.py	Updated example for `trim_weights()` to be more concise and added example for `default_transformations()`
CHANGELOG.md	Added entry documenting synchronization of docstring examples with test cases
.github/workflows/build-and-test.yml	Updated Python version from 3.9 to 3.12 and black version from 24.4.2 to 25.1.0 for linting job

Copilot · 2026-01-12T12:01:17Z

.github/workflows/build-and-test.yml

    - name: Install dependencies
      run: |
-        pip install flake8 black==24.4.2 ruff-api==0.1.0 ufmt==2.8.0 usort==1.0.8.post1
+        pip install flake8 black==25.1.0 ruff-api==0.1.0 ufmt==2.8.0 usort==1.0.8.post1


The black version is updated to 25.1.0 in the workflow file, but requirements-fmt.txt still specifies black==24.4.2. This creates an inconsistency where the CI linting job and local development would use different black versions, potentially causing formatting discrepancies. Either both should be updated together, or this change should be in a separate PR focused on dependency updates.

Suggested change

pip install flake8 black==25.1.0 ruff-api==0.1.0 ufmt==2.8.0 usort==1.0.8.post1

pip install flake8 black==24.4.2 ruff-api==0.1.0 ufmt==2.8.0 usort==1.0.8.post1

Copilot · 2026-01-12T12:01:17Z

.github/workflows/build-and-test.yml

+        python-version: 3.12
    - name: Install dependencies
      run: |
-        pip install flake8 black==24.4.2 ruff-api==0.1.0 ufmt==2.8.0 usort==1.0.8.post1
+        pip install flake8 black==25.1.0 ruff-api==0.1.0 ufmt==2.8.0 usort==1.0.8.post1


The workflow file changes (updating Python version from 3.9 to 3.12 for linting and updating black version from 24.4.2 to 25.1.0) are unrelated to adding docstring examples. According to the project's coding guidelines, each PR should represent one self-contained idea. These infrastructure changes should be in a separate PR to maintain clear change history and easier review/rollback if needed.

…research#259) Summary: **User-facing docstring improvements:** - Resolves facebookresearch#192 - Added comprehensive examples to user-facing function docstrings - Will update missing ones (if any) in a separate PR **Formatting toolchain upgrade to Black 25.1.0:** - Syncs with Meta's internal tooling (D90476287) - Switched ufmt formatter from `ruff-api` to `black` - Updated Black 24.4.2 → 25.1.0 in CI workflow, pre-commit config, and requirements - Added Python 3.14 to Black's `target-version` for forward compatibility - Removed unnecessary `ruff-api` dependency Differential Revision: D90492354

Copilot

Pull request overview

Copilot reviewed 16 out of 16 changed files in this pull request and generated no new comments.

…research#259) Summary: **User-facing docstring improvements:** - Resolves facebookresearch#192 - Added comprehensive examples to user-facing function docstrings - Will update missing ones (if any) in a separate PR **Formatting toolchain upgrade to Black 25.1.0:** - Syncs with Meta's internal tooling (D90476287) - Switched ufmt formatter from `ruff-api` to `black` - Updated Black 24.4.2 → 25.1.0 in CI workflow, pre-commit config, and requirements - Added Python 3.14 to Black's `target-version` for forward compatibility - Removed unnecessary `ruff-api` dependency Differential Revision: D90492354

…esearch#259) Summary: **User-facing docstring improvements:** - Resolves facebookresearch#192 - Added comprehensive examples to user-facing function docstrings - Will update missing ones (if any) in a separate PR **Aligned formatting toolchain with Meta's internal `pyfmt` configuration:** - Switched ufmt formatter from `black` to `ruff-api` to match Meta's internal `tools/lint/pyfmt/config.toml` defaults for `fbcode/`. - This eliminates formatting drift between internal and external CI, ensuring files formatted internally pass GitHub Actions checks. - Updated CI workflow, pre-commit config, and `requirements-fmt.txt` to use `ruff>=0.4.0` instead of Black. - Added `[tool.ruff]` and `[tool.ruff.format]` configuration to `pyproject.toml` for consistent formatting behavior. Differential Revision: D90492354

Copilot

Pull request overview

Copilot reviewed 16 out of 16 changed files in this pull request and generated 1 comment.

Copilot · 2026-01-12T13:04:39Z

requirements-fmt.txt

 # Generated from Meta's internal pyfmt requirements
 # Keep these versions in sync with Meta's internal
-# tools/lint/pyfmt/reqs/requirements-fmt.txt
-black==24.4.2
-ruff-api==0.1.0
-stdlibs==2024.1.28
+# tools/lint/pyfmt configuration
+ruff>=0.4.0
 ufmt==2.8.0


This PR combines two distinct concerns: (1) adding docstring examples to user-facing functions, and (2) migrating the formatting toolchain from black/usort to ruff. According to best practices for this repository, each PR should represent one self-contained idea. Consider splitting this into two PRs: one for the formatting toolchain migration (requirements-fmt.txt, pyproject.toml, .pre-commit-config.yaml, .github/workflows/build-and-test.yml) and another for the docstring example additions (all the .py files). This would make each change easier to review, test, and potentially revert if needed.

…esearch#259) Summary: **User-facing docstring improvements:** - Resolves facebookresearch#192 - Added comprehensive examples to user-facing function docstrings - Will update missing ones (if any) in a separate PR **Aligned formatting toolchain with Meta's internal `pyfmt` configuration:** - Switched ufmt formatter from `black` to `ruff-api` to match Meta's internal `tools/lint/pyfmt/config.toml` defaults for `fbcode/`. - This eliminates formatting drift between internal and external CI, ensuring files formatted internally pass GitHub Actions checks. - Updated CI workflow, pre-commit config, and `requirements-fmt.txt` to use `ruff>=0.4.0` instead of Black. - Added `[tool.ruff]` and `[tool.ruff.format]` configuration to `pyproject.toml` for consistent formatting behavior. Differential Revision: D90492354

meta-codesync · 2026-01-12T14:06:12Z

This pull request has been merged in c8519a2.

Copilot AI review requested due to automatic review settings January 12, 2026 11:56

meta-cla bot added the cla signed label Jan 12, 2026

meta-codesync bot added fb-exported meta-exported labels Jan 12, 2026

Copilot started reviewing on behalf of talgalili January 12, 2026 11:56 View session

Copilot AI reviewed Jan 12, 2026

View reviewed changes

talgalili force-pushed the export-D90492354 branch from da74eed to 25516f6 Compare January 12, 2026 12:34

Copilot AI review requested due to automatic review settings January 12, 2026 12:36

talgalili force-pushed the export-D90492354 branch from 25516f6 to a42a6bd Compare January 12, 2026 12:36

Copilot started reviewing on behalf of talgalili January 12, 2026 12:37 View session

Copilot AI reviewed Jan 12, 2026

View reviewed changes

talgalili force-pushed the export-D90492354 branch from a42a6bd to fa79889 Compare January 12, 2026 12:44

Copilot AI review requested due to automatic review settings January 12, 2026 13:01

talgalili force-pushed the export-D90492354 branch from fa79889 to 2c803da Compare January 12, 2026 13:01

talgalili force-pushed the export-D90492354 branch from 2c803da to a7dface Compare January 12, 2026 13:01

Copilot started reviewing on behalf of talgalili January 12, 2026 13:01 View session

Copilot AI reviewed Jan 12, 2026

View reviewed changes

talgalili force-pushed the export-D90492354 branch from a7dface to 937d7e7 Compare January 12, 2026 13:06

meta-codesync bot closed this in c8519a2 Jan 12, 2026

facebook-github-bot added the Merged label Jan 12, 2026

talgalili mentioned this pull request Jan 12, 2026

Update user-facing functions docstring with examples #258

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update user-facing functions docstring with examples (#258)#259

Update user-facing functions docstring with examples (#258)#259
talgalili wants to merge 1 commit intofacebookresearch:mainfrom
talgalili:export-D90492354

talgalili commented Jan 12, 2026

Uh oh!

meta-codesync bot commented Jan 12, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Jan 12, 2026

Uh oh!

Copilot AI Jan 12, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Jan 12, 2026

Uh oh!

meta-codesync bot commented Jan 12, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	pip install flake8 black==25.1.0 ruff-api==0.1.0 ufmt==2.8.0 usort==1.0.8.post1
	pip install flake8 black==24.4.2 ruff-api==0.1.0 ufmt==2.8.0 usort==1.0.8.post1

Conversation

talgalili commented Jan 12, 2026

Uh oh!

meta-codesync bot commented Jan 12, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Jan 12, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 12, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Jan 12, 2026

Choose a reason for hiding this comment

Uh oh!

meta-codesync bot commented Jan 12, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants