kglite 0.12.7

Pure-Rust knowledge graph engine — Cypher pipeline, snapshot/working CoW transactions, columnar/mmap/disk storage backends, optional dataset loaders (SEC EDGAR, Sodir, Wikidata). PyO3 wrappers live in the sibling kglite-py crate (the Python wheel); embeddable directly from any Rust binary without PyO3 in the dep tree.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114

//! Live SEC integration test — gated behind the
//! `KGLITE_SEC_INTEGRATION_TEST` env var so the default `cargo test`
//! doesn't hit the network.
//!
//! Run with: `KGLITE_SEC_INTEGRATION_TEST=1 cargo test -p kglite-sec --test test_fetch_live`

use std::env;
use std::path::PathBuf;

use kglite::api::datasets::sec::{
    fetch_company_tickers, fetch_quarterly_master_idx, FetchMode, SecClient, Workdir, YearRange,
};

fn live_tests_enabled() -> bool {
    env::var("KGLITE_SEC_INTEGRATION_TEST").is_ok()
}

fn user_agent() -> String {
    env::var("KGLITE_SEC_USER_AGENT")
        .unwrap_or_else(|_| "kglite-sec test runner kglite-tests@example.com".to_string())
}

fn isolated_workdir(name: &str) -> PathBuf {
    let dir = env::temp_dir().join(format!(
        "kglite-sec-live-{}-{}",
        name,
        std::time::SystemTime::now()
            .duration_since(std::time::UNIX_EPOCH)
            .unwrap()
            .as_secs()
    ));
    std::fs::create_dir_all(&dir).unwrap();
    dir
}

#[tokio::test]
async fn fetches_one_quarter_master_idx() {
    if !live_tests_enabled() {
        eprintln!("skipping live test (set KGLITE_SEC_INTEGRATION_TEST=1 to run)");
        return;
    }

    let root = isolated_workdir("master-idx");
    let workdir = Workdir::new(&root);
    let client = SecClient::new(&user_agent()).expect("client");

    // 2023 Q4 is fully closed, so the fetch should hit the cache on
    // the second call.
    let range = YearRange::new(2023, 2023);
    let (dl1, sk1) = fetch_quarterly_master_idx(&client, &workdir, range, 2025, 1)
        .await
        .expect("first fetch");
    assert!(dl1 >= 1, "should download at least one quarter");
    assert_eq!(sk1, 0);

    // Second call must skip — raw/ is immutable for closed quarters.
    let (dl2, sk2) = fetch_quarterly_master_idx(&client, &workdir, range, 2025, 1)
        .await
        .expect("second fetch");
    assert_eq!(dl2, 0, "second call should fetch nothing");
    assert!(sk2 >= 1);

    // The downloaded master.idx file is present on disk for the closed quarter.
    assert!(
        workdir.raw_master_idx(2023, 4).is_file(),
        "fetched master.idx should be on disk"
    );

    std::fs::remove_dir_all(&root).ok();
}

#[tokio::test]
async fn fetches_company_tickers_json() {
    if !live_tests_enabled() {
        return;
    }

    let root = isolated_workdir("tickers");
    let workdir = Workdir::new(&root);
    let client = SecClient::new(&user_agent()).expect("client");

    let dl = fetch_company_tickers(&client, &workdir, false)
        .await
        .expect("fetch");
    assert!(dl);
    assert!(workdir.raw_company_tickers_json().is_file());

    // Re-fetch should skip
    let dl = fetch_company_tickers(&client, &workdir, false)
        .await
        .expect("re-fetch");
    assert!(!dl);

    std::fs::remove_dir_all(&root).ok();
}

#[tokio::test]
async fn rejects_missing_user_agent_on_construct() {
    if !live_tests_enabled() {
        return;
    }
    let err = SecClient::new("").err().expect("should reject");
    assert!(format!("{err}").contains("User-Agent"));
}

#[tokio::test]
async fn handles_unrelated_assertion_about_fetch_mode_enum() {
    if !live_tests_enabled() {
        return;
    }
    // No-op compile check; ensures FetchMode is publicly exposed
    let _ = FetchMode::OnlyIfMissing;
    let _ = FetchMode::Always;
}