feat: adds generation script for income.json

[dsmedia]

• prepares for upcoming metadata improvements in docs: Add missing descriptions, sources, and licenses #663 by tying dataset to specific source: Census Bureau's American Community Survey 3-Year Data (2013), B19001, Household Income in the Past 12 Months (in 2023 Inflation-Adjusted Dollars).

• generates a clone of the existing income.json including the reversed ordering of two income groups (75000 to 99999 comes before 50000 to 74999), in case this was introduced intentionally for educational purposes. if not desired this can be addressed in a future pr. only diff appears to be extra carriage return in legacy json.

• census api documentation for reference

• region mapping and census codes are hard-coded inside script. open to recommendations for if/how to move any configuration to a separate toml or other file.

[dangotbanned]

Note

No need to address in this PR

I'm thinking we should split out some common utilities to another file.

These are some examples of path/filesystem ops in other repos:

• https://github.com/vega/altair/blob/82ec2692efab4ad8f47b39623f1769d90e62f6ae/tools/fs.py
• https://github.com/pypa/hatch/blob/64031c1cf5d02d85203f68cb7a4fd5db2aa7a004/scripts/utils.py

Things I've noticed we have that may be broadly useful

vega-datasets/scripts/income.py

Lines 202 to 204 in 3e30803

	def write_json(data: list[StateIncome], output: Path) -> None:
	"""Writes data to JSON file."""
	output.write_text(json.dumps(data, indent=2), encoding="utf-8")

vega-datasets/scripts/us-state-capitals.py

Lines 164 to 172 in dd43f29

	def write_json(data: Sequence[StateCapitol], output: Path) -> None:
	"""Saves ``data`` to ``output`` with consistent formatting."""
	INDENT, OB, CB, NL = " ", "[", "]", "\n"
	to_str = partial(json.dumps, separators=(", ", ":"))
	with output.open("w", encoding="utf-8", newline="\n") as f:
	f.write(f"{OB}{NL}")
	for record in data[:-1]:
	f.write(f"{INDENT}{to_str(record)},{NL}")
	f.write(f"{INDENT}{to_str(data[-1])}{NL}{CB}{NL}")

vega-datasets/scripts/build_datapackage.py

Lines 583 to 589 in dd43f29

	def read_toml(fp: Path, /) -> dict[str, Any]:
	return tomllib.loads(fp.read_text("utf-8"))
	def read_json(fp: Path, /) -> Any:
	with fp.open(encoding="utf-8") as f:
	return json.load(f)

vega-datasets/scripts/build_datapackage.py

Lines 614 to 617 in 3e30803

	repo_dir: Path = Path(__file__).parent.parent
	data_dir: Path = repo_dir / "data"
	sources_toml: Path = repo_dir / "_data" / ADDITIONS_TOML
	npm_json = repo_dir / NPM_PACKAGE

vega-datasets/scripts/flights.py

Lines 1015 to 1020 in 3e30803

	repo_root = Path(__file__).parent.parent
	source_toml = repo_root / "_data" / "flights.toml"
	app = Flights.from_toml(
	source_toml,
	input_dir=Path.home() / ".vega_datasets",
	output_dir=repo_root / "data",

vega-datasets/scripts/us-state-capitals.py

Lines 38 to 40 in dd43f29

	REPO_ROOT: Path = Path(__file__).parent.parent
	INPUT_DIR: Path = REPO_ROOT / "_data"
	OUTPUT_DIR: Path = REPO_ROOT / "data"

vega-datasets/scripts/us-state-capitals.py

Lines 175 to 176 in dd43f29

	def _get_args(tp: Any, /) -> tuple[Any, ...]:
	return typing.get_args(getattr(tp, "__value__", tp))

vega-datasets/scripts/flights.py

Lines 1008 to 1010 in 3e30803

	def _get_args(tp: Any, /) -> tuple[Any, ...]:
	unwrapped = getattr(tp, "__value__", tp)
	return _typing_get_args(unwrapped)

vega-datasets/scripts/build_datapackage.py

Lines 520 to 524 in dd43f29

	def run_check[T: (str, bytes)](
	args: OneOrSeq[str | Path], /, into: type[T] = str
	) -> sp.CompletedProcess[T]:
	"""
	Run a command in a `subprocess`_, capturing its output.

[dangotbanned]

@dsmedia I'm going to review this in more detail later today.

Wanted to say I'm really impressed by how quickly you were able to adapt to feedback from #668!

Even in the GitHub view, I'm finding it easy to follow 👏

[dangotbanned]

Thanks @dsmedia