Skip to content
19 changes: 19 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -135,6 +135,25 @@ com a indicação `Included`, evitando o limite de texto por célula do Excel.
Consultas mensais sem dias confirmados e marcadores inconsistentes retornam erro.
Relatórios COUNTER padrão não mudam. Consulte o OpenAPI para o contrato completo.

## Relatórios provisórios com cobertura parcial

`GET /r51/extensions/reports/<report_id>` oferece `pr`, `tr`, `tr_j3`, `tr_b3`
e `ir` como relatórios **provisórios, não conformes ao COUNTER**. As rotas
COUNTER padrão permanecem inalteradas.

A rota sempre inclui dias confirmados de meses incompletos, sem exigir
`coverage_policy`; `strict` é rejeitado. Para meses completos, use a rota
COUNTER oficial. Consulte meses inteiros; meses futuros do ano corrente
aparecem somente na cobertura, sem valores estimados.

JSON inclui `coverage` e `warnings`; Excel acrescenta a aba `Coverage` e TSV,
a seção `Usage_Coverage` após os dados. Filtros, formatos e regras estão no
OpenAPI em `/r51/`.

```text
/r51/extensions/reports/tr?platform=scl&begin_date=2025-01&end_date=2025-12
```

## API COUNTER e política de acesso

As rotas GET sob `/r51/` oferecem descoberta, relatórios COUNTER R5.1 e
Expand Down
2 changes: 1 addition & 1 deletion VERSION
Original file line number Diff line number Diff line change
@@ -1 +1 @@
2.7.1
2.8.0
17 changes: 16 additions & 1 deletion counter_api/extensions/dates.py
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,26 @@
from datetime import date

from counter_api.dates import parse_period_inputs
from counter_api.exceptions import invalid_dates
from counter_api.exceptions import insufficient_information, invalid_dates
from counter_api.extensions.contracts import SEGMENT_DIMENSIONS
from counter_api.extensions.query import validate_segmented_period


def parse_provisional_period(params):
if params.get("coverage_policy", "allow_partial") != "allow_partial":
raise insufficient_information("Provisional reports only support allow_partial")

begin, end = parse_period_inputs(params)
if begin.day != 1 or end.day != monthrange(end.year, end.month)[1]:
raise invalid_dates("Provisional reports require full calendar months")

today = date.today()
if begin > today or end.year > today.year:
raise invalid_dates("Period must start by today and end by the current year")

return begin, end


def parse_analytics_period(params):
begin, end = parse_period_inputs(params)
today = date.today()
Expand Down
8 changes: 8 additions & 0 deletions counter_api/extensions/openapi.py
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
from rest_framework import serializers

from counter_api.openapi import CounterReportSerializer


class RankingItemSerializer(serializers.Serializer):
id = serializers.CharField()
Expand Down Expand Up @@ -46,6 +48,12 @@ class CoverageSerializer(serializers.Serializer):
months = CoverageMonthSerializer(many=True)


class ProvisionalReportSerializer(CounterReportSerializer):
provisional = serializers.BooleanField()
coverage = CoverageSerializer()
warnings = serializers.ListField(child=serializers.CharField())


class CoverageResponseSerializer(serializers.Serializer):
coverage = CoverageSerializer(required=False)
warnings = serializers.ListField(child=serializers.CharField(), required=False)
Expand Down
37 changes: 37 additions & 0 deletions counter_api/extensions/reports.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
from functools import partial

from drf_spectacular.utils import extend_schema, extend_schema_view

from counter_api.extensions.dates import parse_provisional_period
from counter_api.extensions.openapi import ProvisionalReportSerializer
from counter_api.generation import generate_report
from counter_api.openapi import REPORT_PARAMETERS, REPORT_RESPONSES
from counter_api.views import ReportView


@extend_schema_view(
get=extend_schema(
tags=["SciELO extensions"],
operation_id="extension_provisional_report",
summary="Generate a provisional Usage report with monthly coverage",
description=(
"Not a COUNTER-compliant report. Reuses PR, TR, TR_J3, TR_B3 and IR "
"filters and formats. Always includes confirmed daily contributions "
"in incomplete months, including the current month. No coverage_policy "
"parameter is needed; strict and invalid values are rejected. Periods must span "
"full calendar months; future months through December of the current "
"year are coverage-only, never zero usage. Coverage describes collection "
"processing, not completeness of the source. JSON, XLSX and TSV retain "
"coverage and warnings. Standard COUNTER routes are unchanged."
),
parameters=REPORT_PARAMETERS,
responses={
**REPORT_RESPONSES,
(200, "application/json"): ProvisionalReportSerializer,
},
)
)
class ProvisionalReportView(ReportView):
period_parser = staticmethod(parse_provisional_period)
report_generator = staticmethod(partial(generate_report, provisional=True))
filename_prefix = "provisional_"
6 changes: 6 additions & 0 deletions counter_api/extensions/urls.py
Original file line number Diff line number Diff line change
@@ -1,8 +1,14 @@
from django.urls import path

from counter_api.extensions.reports import ProvisionalReportView
from counter_api.extensions.views import CapabilitiesView, DistributionView, RankingView

urlpatterns = [
path(
"reports/<str:report_id>",
ProvisionalReportView.as_view(),
name="extension-provisional-report",
),
path("capabilities", CapabilitiesView.as_view(), name="extension-capabilities"),
path("distribution", DistributionView.as_view(), name="extension-distribution"),
path("ranking", RankingView.as_view(), name="extension-ranking"),
Expand Down
46 changes: 43 additions & 3 deletions counter_api/generation.py
Original file line number Diff line number Diff line change
@@ -1,19 +1,49 @@
from datetime import date

from counter_api.availability import split_period
from counter_api.exceptions import CounterAPIError, service_unavailable
from counter_api.extensions.coverage import coverage_fields, resolve_coverage
from counter_api.integrity import metric_invariant_errors
from counter_api.parameters import parse_parameters, report_parameters
from counter_api.query import ReportQuery
from counter_api.reports import build_report


def generate_report(report_id, platform, begin, end, query_params):
months, pending, unavailable = split_period(platform, begin, end)
def generate_report(
report_id, platform, begin, end, query_params, *, provisional=False
):
query = ReportQuery()
coverage = None

if provisional:
coverage = resolve_coverage(
query.client, platform, begin, end, "allow_partial", False, query.deadline
)
months = [
date.fromisoformat(f"{month}-01") for month in coverage["included_months"]
]
pending = [
date.fromisoformat(f"{item['month']}-01")
for item in coverage["months"]
if not item["complete_month"] and item["status"] != "future"
]
unavailable = []

query_params = {
key: value
for key, value in query_params.items()
if key != "coverage_policy"
}
else:
months, pending, unavailable = split_period(platform, begin, end)

params = parse_parameters(query_params, report_id)
params["pending_months"] = pending
params["unavailable_months"] = unavailable

report_params = report_parameters(report_id, params)
query = ReportQuery()
if coverage is not None:
report_params["coverage"] = coverage

if params.get("Item_ID"):
try:
Expand Down Expand Up @@ -51,4 +81,14 @@ def generate_report(report_id, platform, begin, end, query_params):
if errors:
raise service_unavailable(f"Book metrics inconsistent: {errors[0]}")

if coverage is not None:
payload.update(coverage_fields(coverage))
payload["provisional"] = True
payload["Report_Header"]["Report_Name"] += " — Usage provisional report"
payload["warnings"].insert(
0,
"Usage provisional report, not a COUNTER-compliant report. "
"Counts may change as processing completes.",
)

return payload, query.deadline
16 changes: 8 additions & 8 deletions counter_api/query.py
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@

from counter_api.constants import COMPOSITE_PAGE_SIZE
from counter_api.exceptions import incongruous_filter, invalid_filter
from counter_api.extensions.coverage import metric_sum
from counter_api.identifiers import ITEM_ID_FIELDS
from counter_api.metadata import fetch_metadata
from counter_api.search import composite_pages, search
Expand Down Expand Up @@ -237,14 +238,13 @@ def _query_body(self, months, after, report_id, params=None):
"rows": {
"composite": composite,
"aggs": {
"total_requests": {"sum": {"field": "total_requests"}},
"total_investigations": {
"sum": {"field": "total_investigations"}
},
"unique_requests": {"sum": {"field": "unique_requests"}},
"unique_investigations": {
"sum": {"field": "unique_investigations"}
},
metric: {"sum": metric_sum(metric, params.get("coverage"))}
for metric in (
"total_requests",
"total_investigations",
"unique_requests",
"unique_investigations",
)
},
}
},
Expand Down
53 changes: 52 additions & 1 deletion counter_api/tabular.py
Original file line number Diff line number Diff line change
@@ -1,7 +1,9 @@
import csv
import json
from codecs import BOM_UTF8
from datetime import date
from io import StringIO
from itertools import chain
from tempfile import SpooledTemporaryFile
from time import monotonic

Expand Down Expand Up @@ -57,6 +59,11 @@ def build_workbook(report, deadline=None):

sheet.append(row)

if report.get("provisional"):
coverage_sheet = workbook.create_sheet(title="Coverage")
for row in _coverage_rows(report):
coverage_sheet.append(row)

output = SpooledTemporaryFile(max_size=SPOOL_SIZE)
if deadline and monotonic() >= deadline:
workbook.close()
Expand All @@ -75,7 +82,7 @@ def build_tsv(report, deadline=None):
line = StringIO(newline="")
writer = csv.writer(line, delimiter="\t", lineterminator="\n")

for row in _report_rows(report):
for row in chain(_report_rows(report), _coverage_rows(report)):
if deadline and monotonic() >= deadline:
output.close()
raise service_unavailable()
Expand All @@ -90,6 +97,50 @@ def build_tsv(report, deadline=None):
return output


def _coverage_rows(report):
if not report.get("provisional"):
return

coverage = report["coverage"]
yield ()
yield ("Usage_Coverage", "Provisional, not a COUNTER-compliant report")
yield ("Policy", coverage["policy"])
yield ("Status", coverage["status"])
yield ("Basis", coverage["basis"])

for warning in report["warnings"]:
yield ("Warning", warning)

yield (
"Month",
"Status",
"Included",
"Complete_Month",
"Requested_Days",
"Confirmed_Days",
"Missing_Days",
"Future_Days",
)

included = set(coverage["included_months"])
for month in coverage["months"]:
yield (
month["month"],
month["status"],
month["month"] in included,
month["complete_month"],
*(
json.dumps(month[field], separators=(",", ":"))
for field in (
"requested_days",
"confirmed_days",
"missing_days",
"future_days",
)
),
)


def _report_rows(report):
header = report["Report_Header"]
yield from (
Expand Down
1 change: 1 addition & 0 deletions counter_api/tests/test_access.py
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@
"/r51/extensions/capabilities",
"/r51/extensions/ranking",
"/r51/extensions/distribution",
"/r51/extensions/reports/tr",
)


Expand Down
1 change: 1 addition & 0 deletions counter_api/tests/test_http.py
Original file line number Diff line number Diff line change
Expand Up @@ -114,6 +114,7 @@ def test_swagger_and_schema_are_public_and_limited_to_counter(self):
"/r51/extensions/capabilities",
"/r51/extensions/distribution",
"/r51/extensions/ranking",
"/r51/extensions/reports/{report_id}",
},
)
self.assertFalse(payload.get("security"))
Expand Down
Loading
Loading