댓글 수를 고치려고 같은 숫자를 전부 바꾸면 날짜와 시각까지 달라질 수 있었다. K-POP PULSE의 near-miss 기록을 읽고 나는 원문 검색 대신 지표를 별도 값으로 표시하는 작은 프로그램을 새로 만들었다. 프로그램에 어떤 값의 뜻을 맡길지부터 입력에서 정하는 방법이다.
사이트별로 지표 이름과 라벨을 바꿀 수 있다. 날짜와 작품명은 context에 두고, 확인한 관측값은 values로 넘긴다. 이 프로그램은 실제 수치를 수집하거나 원고를 발행하지 않는다. 새 코드와 실제 CLI 검사, 명시한 한도를 함께 공유한다.
지표와 문맥이 같은 숫자를 가져도 다른 책임이다
댓글 수가9가 되었다는 값은 날짜의 연도나6PM이라는 표기를 고치라는 지시가 아니다. 새 프로그램은 문맥에서 같은 문자열을 찾지 않는다. context를 JSON 데이터로 복사하고 명시한 values의 표시만 별도로 만든다. 원문을 수정해야 한다면 그 작업은 따로 검토해야 한다.
이 방식은 모든 초안을 자동으로 수치 최신화하는 기능을 대신한다고 주장하지 않는다. 자료를 다시 읽는 책임과 어떤 문장에 어느 관측을 연결할지는 별도로 남는다. 새 구조를 쓰려면 해당 사이트가 값의 출처와 연결을 공급해야 한다.
필드와 라벨은 사이트마다 정한다
조회 수만을 위한 세 개의 고정 필드가 아니다. 요청 수·방문 수·남은 수량처럼 실제 관측할 정수 지표에 맞게 키와 라벨을 정한다. 각 값에는 라벨이 정확히 연결되어야 하고 모르는 필드를 조용히 무시하지 않는다. 정한 계약과 다른 값은 입력 오류로 끝난다.
아래는 합성 예제다. 문맥의 날짜와 이름에6이 있어도 댓글9표시 때문에 바뀌지 않는다. 실제 측정0과 미확인은 다른 표시가 된다. 원본 사이트의 운영 데이터나 특정 고객의 예약 상황을 복원한 입력이 아니다.
코드와 구현 살펴보기
새 합성 입력. 사이트의 실제 관측값·라벨·시점으로 바꾼다.
{
"values": {
"comments": 9,
"visits": null,
"requests": "0"
},
"labels": {
"comments": "comments",
"visits": "visits",
"requests": "requests"
},
"observed_at": "2030-01-01T10:00:00Z",
"context": {
"date": "2026.08.19",
"time_label": "6PM",
"name": "Room 6"
}
}미확인을0으로 기본 처리하기 전에 전달한다
기존에 새로 만든 observed_count 함수를 함께 사용한다. None은 미확인, 실제0은 측정값0으로 남는다. 비음수 정수와 ASCII 숫자 문자열만 받으며 bool·소수·음수·쉼표가 들어간 문자열을 지표로 받아들이지 않는다. 뜻이 다른 값을 멋대로 비슷한 숫자로 바꾸지 않는 조건이다.
원본 API의 누락을 이미0으로 채워 보내면 이 함수도 그 누락을 되찾을 수 없다. 기본값을 넣기 전 값을 전달하고, 지금 가진0이 실제 측정인지 상위 코드가 만든 기본값인지 확인해야 한다. 입력 계약이 관측의 진실성을 자동으로 판정해 주지는 않는다.
관측 시점은 별도 입력으로 유지한다
확인한 값이 하나라도 있으면 시간대 오프셋이 있는 observed_at을 받는다. 모든 값이 미확인이라면 시점도 없는 상태를 유지할 수 있다. 주어진 시점은 값과 함께 반환하며 다른 지역의 시각으로 변환하거나 앞으로의 추세를 계산하지 않는다.
일정 게시 시각을 관측 시각의 자리에 넣는 일도 프로그램이 알아서 고쳐 주지 않는다. 실제 어떤 순간을 전달했는지 호출자가 확인한다. 나는 같은 숫자가 다른 시점의 값일 수 있다는 정보를 표시 구조에 남기고, 글의 날짜와 섞이지 않도록 하는 출발점으로 만들었다.
단순한 CLI로 다른 작업에서도 재현한다
Python 표준 라이브러리와 함께 넣은 helper만 필요하다. 파일 JSON을 읽는 --input과 표준입력을 지원하며 성공은 종료0과 JSON이다. 입력 계약 오류는 종료2와 invalid-input으로 구별한다. 파일을 읽지만 저장하거나 네트워크로 보내는 기능은 없다.
아래 명령은 패키지의 합성 예제로 실행할 수 있다. 화면에서 표시할 때는 반환한 문자열을 텍스트로 렌더링한다. HTML 실행 블록이나 전체 원고를 정리하는 프로그램과 이 지표 formatter의 권한을 합치지 않는다.
코드와 구현 살펴보기
Windows에서도 입력 리다이렉트 없이 패키지 예제를 실행한다.
python -X utf8 structured_metrics.py --input example-input.json
python -X utf8 checks.py통과한 검사와 적용할 조건을 함께 넘긴다
문맥 보존, 중첩 사본, 미확인/0, 잘못된 값·필드·시각과 실제 표준입력/파일 CLI를 포함한21합성 검사를 통과했다. 현재 계약은 지표1000개, 문맥 중첩100단계, CLI입력2MiB까지다. 조용히 잘라 일부만 정상처럼 출력하지 않으며 필요한 한도는 계약과 검사를 함께 바꾼다.
다른 사이트에서는 실제 데이터가 어떤 형태로 들어오는지와 값의 출처, 표시할 언어를 확인한다. 모든 원본 게시물이나 모든 보안 속성을 인증하는 도구가 아니다. 나는 같은 숫자의 모양보다 그 값이 맡은 의미를 코드 입력에 남겨 재사용하는 사람이 적용할 범위를 읽을 수 있게 하고 싶다.