Add BLS client library, example scripts, and usage docs

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

bls_client/queries/employment.py

@@ -0,0 +1,133 @@
+"""
+Pre-built employment series IDs — ready to pass to BLSClient.fetch().
+
+All functions return a single series ID string or a dict of {label: series_id}.
+"""
+
+from ..series import laus_state, laus_msa, ces_national, ces_state, jolts
+
+# ---------------------------------------------------------------------------
+# National employment
+# ---------------------------------------------------------------------------
+def nonfarm_payrolls(seasonal: bool = True) -> str:
+    """Total nonfarm payroll employment (CES). The headline monthly jobs number."""
+    return ces_national("total_nonfarm", "employees", seasonal)
+
+
+def private_payrolls(seasonal: bool = True) -> str:
+    """Total private sector payroll employment."""
+    return ces_national("total_private", "employees", seasonal)
+
+
+def government_employment(seasonal: bool = True) -> str:
+    """Total government employment (federal + state + local)."""
+    return ces_national("government", "employees", seasonal)
+
+
+def manufacturing_employment(seasonal: bool = True) -> str:
+    return ces_national("manufacturing", "employees", seasonal)
+
+
+def national_unemployment_rate(seasonal: bool = True) -> str:
+    """National unemployment rate from the CPS (U-3 rate)."""
+    return "LNS14000000" if seasonal else "LNU04000000"
+
+
+def national_labor_force_participation(seasonal: bool = True) -> str:
+    """National labor force participation rate."""
+    return "LNS11300000" if seasonal else "LNU01300000"
+
+
+# ---------------------------------------------------------------------------
+# LAUS — state unemployment
+# ---------------------------------------------------------------------------
+def dc_unemployment_rate(seasonal: bool = False) -> str:
+    return laus_state(11, "rate", seasonal)
+
+
+def md_unemployment_rate(seasonal: bool = False) -> str:
+    return laus_state(24, "rate", seasonal)
+
+
+def va_unemployment_rate(seasonal: bool = False) -> str:
+    return laus_state(51, "rate", seasonal)
+
+
+def state_unemployment(state_fips: int, seasonal: bool = False) -> dict:
+    """All four LAUS measures for a state."""
+    return {
+        "rate":       laus_state(state_fips, "rate",       seasonal),
+        "unemployed": laus_state(state_fips, "unemployed", seasonal),
+        "employed":   laus_state(state_fips, "employed",   seasonal),
+        "laborforce": laus_state(state_fips, "laborforce", seasonal),
+    }
+
+
+def dc_region_unemployment() -> dict:
+    """Unemployment rates for DC, MD, VA states + DC Metro, Baltimore, Richmond MSAs."""
+    return {
+        "DC State":     laus_state(11, "rate"),
+        "Maryland":     laus_state(24, "rate"),
+        "Virginia":     laus_state(51, "rate"),
+        "DC Metro MSA": laus_msa(11, 47900, "rate"),
+        "Baltimore MSA":laus_msa(24, 12580, "rate"),
+        "Richmond MSA": laus_msa(51, 40060, "rate"),
+    }
+
+
+# ---------------------------------------------------------------------------
+# JOLTS
+# ---------------------------------------------------------------------------
+def job_openings_level(seasonal: bool = True) -> str:
+    return jolts("job_openings", "L", seasonal=seasonal)
+
+
+def job_openings_rate(seasonal: bool = True) -> str:
+    return jolts("job_openings", "R", seasonal=seasonal)
+
+
+def quits_level(seasonal: bool = True) -> str:
+    return jolts("quits", "L", seasonal=seasonal)
+
+
+def hires_level(seasonal: bool = True) -> str:
+    return jolts("hires", "L", seasonal=seasonal)
+
+
+def layoffs_level(seasonal: bool = True) -> str:
+    return jolts("layoffs", "L", seasonal=seasonal)
+
+
+def jolts_dashboard() -> dict:
+    """All five JOLTS measures (levels, SA) as a labeled dict."""
+    return {
+        "Job Openings":      job_openings_level(),
+        "Hires":             hires_level(),
+        "Quits":             quits_level(),
+        "Layoffs":           layoffs_level(),
+        "Total Separations": jolts("total_separations", "L"),
+    }
+
+
+# ---------------------------------------------------------------------------
+# QCEW
+# ---------------------------------------------------------------------------
+def qcew_national_private() -> str:
+    """QCEW — national, private sector, all industries, quarterly."""
+    return "ENU0000010510000"
+
+
+def qcew_dc_private() -> str:
+    """QCEW — DC, private sector, all industries."""
+    return "ENU1100010510000"
+
+
+def qcew_state(state_fips: int, ownership: str = "5") -> str:
+    """
+    QCEW state-level series.
+
+    Args:
+        state_fips: 2-digit FIPS
+        ownership:  "0"=all, "5"=private, "1"=federal, "2"=state, "3"=local
+    """
+    return f"ENU{state_fips:02d}0001{ownership}10000"