…1162)

Closes #1161

Adds parameter tables and formal API reference sections to three pages
that previously had examples but no parameter documentation.

pushgateway.md: documents push_to_gateway, pushadd_to_gateway,
delete_from_gateway, instance_ip_grouping_key, and all four built-in
handlers (default, basic_auth, tls_auth, passthrough_redirect).

textfile.md: documents write_to_textfile with all four parameters
including the previously undocumented escaping and tmpdir, plus atomic
write semantics and error behavior.

multiprocess/_index.md: documents MultiProcessCollector constructor and
mark_process_dead with parameter tables including the previously
undocumented path parameter on both.

Signed-off-by: k1chik <107162115+k1chik@users.noreply.github.com>

Assigning the .time() context manager (with ... as t) now yields a Timer
whose .duration attribute holds the observed value in seconds after the
block exits. This lets callers reuse the measurement (logging, further
metrics) without calling default_timer() a second time.

Signed-off-by: Lukáš Vokráčko <lukas@vokracko.cz>

…asses (#1169)

Closes #1163

collector/custom.md: Collector protocol section (collect/describe), value vs
labels mutual exclusivity note, full constructor and add_metric tables for
GaugeMetricFamily, CounterMetricFamily, SummaryMetricFamily,
HistogramMetricFamily, and InfoMetricFamily, plus a runnable real-world example.

collector/_index.md: constructor parameter tables for ProcessCollector,
PlatformCollector, and GCCollector, with exported metrics listed for each.

registry/_index.md (new): CollectorRegistry constructor and all public methods
(register, unregister, collect, restricted_registry, get_sample_value,
set_target_info, get_target_info), the global REGISTRY instance, and examples
for isolated registry usage and registry=None.

All code examples verified by running them in Python.

Signed-off-by: k1chik <107162115+k1chik@users.noreply.github.com>

* docs: clarify collect() generator usage and API Reference snippet context

Add a note to the collect() protocol section explaining that yield is idiomatic
(generator iterates lazily, no state between scrapes) and a preamble to the API
Reference section clarifying that code snippets belong inside a collect() method.

Follows up on review feedback in #1169.

Signed-off-by: k1chik <kkukdia@gmail.com>

* docs: split InfoMetricFamily example into two separate blocks

The single block with two yield statements looked like one collect() yielding
both patterns. Split into labelled prose + code pairs to make clear they are
alternatives, not sequential yields.

Signed-off-by: k1chik <kkukdia@gmail.com>

---------

Signed-off-by: k1chik <kkukdia@gmail.com>

Use sub-class of ValueError instead of ValueError, so that we can
distinguish issues caused by wrong input (like invalid name format)
from duplicate metrics being registered into the same registry.

Signed-off-by: Takashi Kajinami <kajinamit@oss.nttdata.com>

Signed-off-by: prombot <prometheus-team@googlegroups.com>

Signed-off-by: Om Pathak <ompathak@gmail.com>
Co-authored-by: Om Pathak <ompathak@gmail.com>

…uteError (#1184)

Fixes #707. clear() unconditionally acquired self._lock, which is
never created for metrics with no labelnames, causing an
AttributeError. Per discussion in the issue (csmarchbanks,
roidelapluie, sdfordham, tomprince), a label-less metric has no
labelsets to clear, so clear() now treats this as a no-op rather
than raising.

Signed-off-by: Om Pathak <ompathak@gmail.com>
Co-authored-by: Om Pathak <ompathak@gmail.com>

Signed-off-by: Grégoire Deveaux <gregoire.deveaux@gitguardian.com>

This adds the tls_min_version and tls_max_version parameters for
the start_wsgi_server (and start_http_server), allowing to restrict
the min/max TLS version negotiated for accessing the server.

New unit tests under TestWsgiTLS were added, which test the version
parameters as well as the rest of TLS capabilities for the
start_wsgi_server (TLS on/off, mTLS), since those previously didn't have
any test coverage.

Signed-off-by: Jaromir Wysoglad <jwysogla@redhat.com>

Enum.__init__ called super().__init__() -- which registers the collector
in the CollectorRegistry -- before validating that states is non-empty
and that the metric name does not overlap a label name. When either
check failed, the ValueError was raised as expected, but a half-built
Enum (whose _states was never assigned) had already been registered.

That left the registry in a broken state: the name was permanently
taken, so recreating the metric raised 'Duplicated timeseries', and any
subsequent scrape crashed with

    AttributeError: 'Enum' object has no attribute '_states'

when _child_samples iterated self._states. A realistic trigger is
building the states list from configuration that turns out to be empty.

Gauge and Histogram already validate before calling super().__init__();
this moves Enum's two guards ahead of registration to match, so a failed
constructor leaves the registry untouched.

Add test_failed_init_does_not_pollute_registry, which asserts that after
two failed Enum constructions the name is still free, the metric can be
created, and the registry scrapes cleanly.

Signed-off-by: Sean Kim <skim8705@gmail.com>

floatToGoString reproduces Go's strconv.FormatFloat(f, 'g', -1, 64),
which pads a float's exponent to a minimum of two digits. The exponent
was formatted as 'e+0{dot - 1}', which hard-codes a single leading zero
and only produces the right width while dot - 1 is a single digit. Once
the exponent reaches two digits (values >= 1e10, whose repr is still
plain decimal) it over-pads, e.g. 1e10 became '1e+010' instead of Go's
'1e+10'. That affects any emitted sample value or le/quantile bucket
boundary at or above 1e10.

Use '{dot - 1:02d}' so the exponent is zero-padded to a minimum of two
digits and not beyond, matching Go.

Add tests/test_utils.py covering both the previously-correct single-digit
exponents and the two-digit exponents that regressed.

Signed-off-by: Sean Kim <skim8705@gmail.com>

Signed-off-by: prombot <prometheus-team@googlegroups.com>

Signed-off-by: prombot <prometheus-team@googlegroups.com>

* fix: make test suite pass on Windows and Python 3.12+

- Fix event loop issues in ASGI tests under newer asgiref by wrapping communicator setup in an async coroutine run on the loop.
- Fix mmap file locking (PermissionError: [WinError 32]) on Windows in multiprocess tests by closing open database handles before unlinking/removing directories.
- Skip case-sensitive env var deprecation warning assertion on Windows where environment variables are case-insensitive.
- Conditionally define the parser benchmark test to avoid failure when pytest-benchmark is not installed.

Signed-off-by: MelvinjoseC <165891174+MelvinjoseC@users.noreply.github.com>

* fix: resolve lint/typing issues and add Windows CI coverage

Signed-off-by: MelvinjoseC <165891174+MelvinjoseC@users.noreply.github.com>

---------

Signed-off-by: MelvinjoseC <165891174+MelvinjoseC@users.noreply.github.com>

_parse_nh_struct parsed the sum field with int(), so a native histogram
whose sum is not integral failed to parse with

    ValueError: invalid literal for int() with base 10: '100.5'

NativeHistogram.sum_value is a float and the OpenMetrics writer emits the
sum verbatim (e.g. sum:100.5), so the library could not parse its own
output for the common case of a non-integer sum. Parse sum with float()
to match; count, schema and zero_count remain int as they are genuinely
integers.

Add test_native_histogram_float_sum, which parses a native histogram
with a fractional sum and checks it round-trips to sum_value 100.5.

Signed-off-by: Sean Kim <skim8705@gmail.com>

When a collector is registered under support_collectors_without_names
with no metric names, register() appends it to _collectors_without_names
in addition to the usual bookkeeping. unregister() only cleaned up
_collector_to_names and _names_to_collectors, so the collector stayed in
_collectors_without_names and kept being collected.

A normal collect() no longer returned the collector's metrics, but
RestrictedRegistry.collect() -- which seeds its collector set from
_collectors_without_names -- still did, so an unregistered collector's
samples reappeared under restricted_registry(). unregister() now also
drops the collector from that list.

Add test_unregister_removes_no_names_collector, asserting a nameless
collector is no longer collected by a restricted registry after it has
been unregistered.

Signed-off-by: Sean Kim <skim8705@gmail.com>

_is_valid_exemplar_metric() guarded histograms with

    if metric.type in ('histogram') and sample.name.endswith('_bucket') or sample.name == metric.name:

Because 'and' binds tighter than 'or', this parsed as

    (metric.type in ('histogram') and sample.name.endswith('_bucket')) or (sample.name == metric.name)

so the trailing 'sample.name == metric.name' clause fired for every
metric type. As a result the OpenMetrics writer emitted exemplars on
gauges, info, stateset, summary and untyped metrics whenever a sample
name equalled the metric name -- output that the library's own
OpenMetrics parser rejects (only histogram/gaugehistogram buckets,
counter _total, and native histograms may carry exemplars).

Group the histogram condition correctly so the same-name clause (which
exists to allow native-histogram exemplars) only applies to histograms.
While here, replace the 'metric.type in (...)' single-string membership
checks with '==' -- they were doing substring matching, not the
intended equality.

Add test_gauge_exemplar, which asserts a gauge sample carrying an
exemplar raises ValueError, matching the existing untyped/non-bucket
exemplar tests.

Signed-off-by: Sean Kim <skim8705@gmail.com>