Option to resolve at a fixed timestamp with pip-compile --exclude-newer YYYY-MM-DD (#434)

This works by filtering out files with a more recent upload time, so if
the index you use does not provide upload times, the results might be
inaccurate. pypi provides upload times for all files. This is, the field
is non-nullable in the warehouse schema, but the simple API PEP does not
know this field.

If you have only pypi dependencies, this means deterministic,
reproducible(!) resolution. We could try doing the same for git repos
but it doesn't seem worth the effort, i'd recommend pinning commits
since git histories are arbitrarily malleable and also if you care about
reproducibility and such you such not use git dependencies but a custom
index.

Timestamps are given either as RFC 3339 timestamps such as
`2006-12-02T02:07:43Z` or as UTC dates in the same format such as
`2006-12-02`. Dates are interpreted as including this day, i.e. until
midnight UTC that day. Date only is required to make this ergonomic and
midnight seems like an ergonomic choice.

In action for `pandas`:

```console
$ target/debug/puffin pip-compile --exclude-newer 2023-11-16 target/pandas.in
Resolved 6 packages in 679ms
# This file was autogenerated by Puffin v0.0.1 via the following command:
#    target/debug/puffin pip-compile --exclude-newer 2023-11-16 target/pandas.in
numpy==1.26.2
    # via pandas
pandas==2.1.3
python-dateutil==2.8.2
    # via pandas
pytz==2023.3.post1
    # via pandas
six==1.16.0
    # via python-dateutil
tzdata==2023.3
    # via pandas
$ target/debug/puffin pip-compile --exclude-newer 2022-11-16 target/pandas.in
Resolved 5 packages in 655ms
# This file was autogenerated by Puffin v0.0.1 via the following command:
#    target/debug/puffin pip-compile --exclude-newer 2022-11-16 target/pandas.in
numpy==1.23.4
    # via pandas
pandas==1.5.1
python-dateutil==2.8.2
    # via pandas
pytz==2022.6
    # via pandas
six==1.16.0
    # via python-dateutil
$ target/debug/puffin pip-compile --exclude-newer 2021-11-16 target/pandas.in
Resolved 5 packages in 594ms
# This file was autogenerated by Puffin v0.0.1 via the following command:
#    target/debug/puffin pip-compile --exclude-newer 2021-11-16 target/pandas.in
numpy==1.21.4
    # via pandas
pandas==1.3.4
python-dateutil==2.8.2
    # via pandas
pytz==2021.3
    # via pandas
six==1.16.0
    # via python-dateutil
```

Author: konstin

Cargo.lock

@@ -24,6 +24,7 @@ camino = { version = "1.1.6", features = ["serde1"] }
 clap = { version = "4.4.7" }
 colored = { version = "2.0.4" }
 configparser = { version = "3.0.2" }
+chrono = { version = "0.4.31" }
 csv = { version = "1.3.0" }
 data-encoding = { version = "2.4.0" }
 directories = { version = "5.0.1" }

Cargo.toml

@@ -36,6 +36,7 @@ anstream = { workspace = true }
 anyhow = { workspace = true }
 bitflags = { workspace = true }
 cacache = { workspace = true }
+chrono = { workspace = true }
 clap = { workspace = true, features = ["derive"] }
 colored = { workspace = true }
 directories = { workspace = true }

crates/puffin-cli/Cargo.toml

@@ -7,6 +7,7 @@ use std::str::FromStr;
 use std::{env, fs};
 
 use anyhow::{anyhow, Result};
+use chrono::{DateTime, Utc};
 use colored::Colorize;
 use itertools::Itertools;
 use tracing::debug;
@@ -42,6 +43,7 @@ pub(crate) async fn pip_compile(
     index_urls: Option<IndexUrls>,
     no_build: bool,
     python_version: Option<PythonVersion>,
+    exclude_newer: Option<DateTime<Utc>>,
     cache: &Path,
     mut printer: Printer,
 ) -> Result<ExitStatus> {
@@ -102,6 +104,7 @@ pub(crate) async fn pip_compile(
         resolution_mode,
         prerelease_mode,
         project,
+        exclude_newer,
     );
 
     // Detect the current Python interpreter.

crates/puffin-cli/src/commands/pip_compile.rs

@@ -1,8 +1,10 @@
 use std::borrow::Cow;
 use std::path::{Path, PathBuf};
 use std::process::ExitCode;
+use std::str::FromStr;
 
 use anyhow::Result;
+use chrono::{DateTime, Days, NaiveDate, NaiveTime, Utc};
 use clap::{Args, Parser, Subcommand};
 use colored::Colorize;
 use directories::ProjectDirs;
@@ -85,6 +87,24 @@ enum Commands {
     Remove(RemoveArgs),
 }
 
+/// Clap parser for the union of date and datetime
+fn date_or_datetime(input: &str) -> Result<DateTime<Utc>, String> {
+    let date_err = match NaiveDate::from_str(input) {
+        Ok(date) => {
+            // Midnight that day is 00:00:00 the next day
+            return Ok((date + Days::new(1)).and_time(NaiveTime::MIN).and_utc());
+        }
+        Err(err) => err,
+    };
+    let datetime_err = match DateTime::parse_from_rfc3339(input) {
+        Ok(datetime) => return Ok(datetime.with_timezone(&Utc)),
+        Err(err) => err,
+    };
+    Err(format!(
+        "Neither a valid date ({date_err}) not a valid datetime ({datetime_err})"
+    ))
+}
+
 #[derive(Args)]
 #[allow(clippy::struct_excessive_bools)]
 struct PipCompileArgs {
@@ -130,14 +150,28 @@ struct PipCompileArgs {
     #[clap(long)]
     upgrade: bool,
 
-    /// Don't build source distributions. This means resolving will not run arbitrary code. The
-    /// cached wheels of already built source distributions will be reused.
+    /// Don't build source distributions.
+    ///
+    /// This means resolving will not run arbitrary code. The cached wheels of already built source
+    /// distributions will be reused.
     #[clap(long)]
     no_build: bool,
 
     /// The minimum Python version that should be supported.
     #[arg(long, short, value_enum)]
     python_version: Option<PythonVersion>,
+
+    /// Try to resolve at a past time.
+    ///
+    /// This works by filtering out files with a more recent upload time, so if the index you use
+    /// does not provide upload times, the results might be inaccurate. pypi provides upload times
+    /// for all files.
+    ///
+    /// Timestamps are given either as RFC 3339 timestamps such as `2006-12-02T02:07:43Z` or as
+    /// UTC dates in the same format such as `2006-12-02`. Dates are interpreted as including this
+    /// day, i.e. until midnight UTC that day.
+    #[arg(long, value_parser = date_or_datetime)]
+    exclude_newer: Option<DateTime<Utc>>,
 }
 
 #[derive(Args)]
@@ -272,6 +306,7 @@ async fn inner() -> Result<ExitStatus> {
                 index_urls,
                 args.no_build,
                 args.python_version,
+                args.exclude_newer,
                 &cache_dir,
                 printer,
             )

crates/puffin-cli/src/main.rs

@@ -31,6 +31,31 @@ fn make_venv_py312(temp_dir: &TempDir, cache_dir: &TempDir) -> PathBuf {
     venv.to_path_buf()
 }
 
+/// Resolve a specific version of Django from a `requirements.in` file.
+#[test]
+fn compile_requirements_in() -> Result<()> {
+    let temp_dir = TempDir::new()?;
+    let cache_dir = TempDir::new()?;
+    let venv = make_venv_py312(&temp_dir, &cache_dir);
+
+    let requirements_in = temp_dir.child("requirements.in");
+    requirements_in.write_str("django==5.0b1")?;
+
+    insta::with_settings!({
+        filters => INSTA_FILTERS.to_vec()
+    }, {
+        assert_cmd_snapshot!(Command::new(get_cargo_bin(BIN_NAME))
+            .arg("pip-compile")
+            .arg("requirements.in")
+            .arg("--cache-dir")
+            .arg(cache_dir.path())
+            .env("VIRTUAL_ENV", venv.as_os_str())
+            .current_dir(&temp_dir));
+    });
+
+    Ok(())
+}
+
 #[test]
 fn missing_requirements_in() -> Result<()> {
     let temp_dir = TempDir::new()?;
@@ -68,31 +93,6 @@ fn missing_venv() -> Result<()> {
     Ok(())
 }
 
-/// Resolve a specific version of Django from a `requirements.in` file.
-#[test]
-fn compile_requirements_in() -> Result<()> {
-    let temp_dir = TempDir::new()?;
-    let cache_dir = TempDir::new()?;
-    let venv = make_venv_py312(&temp_dir, &cache_dir);
-
-    let requirements_in = temp_dir.child("requirements.in");
-    requirements_in.write_str("django==5.0b1")?;
-
-    insta::with_settings!({
-        filters => INSTA_FILTERS.to_vec()
-    }, {
-        assert_cmd_snapshot!(Command::new(get_cargo_bin(BIN_NAME))
-            .arg("pip-compile")
-            .arg("requirements.in")
-            .arg("--cache-dir")
-            .arg(cache_dir.path())
-            .env("VIRTUAL_ENV", venv.as_os_str())
-            .current_dir(&temp_dir));
-    });
-
-    Ok(())
-}
-
 /// Resolve a specific version of Django from a `pyproject.toml` file.
 #[test]
 fn compile_pyproject_toml() -> Result<()> {
@@ -1206,11 +1206,7 @@ dependencies = ["django==5.0b1", "django==5.0a1"]
     )?;
 
     insta::with_settings!({
-        filters => vec![
-            (r"\d(ms|s)", "[TIME]"),
-            (r"#    .* pip-compile", "#    [BIN_PATH] pip-compile"),
-            (r"--cache-dir .*", "--cache-dir [CACHE_DIR]"),
-        ]
+        filters => INSTA_FILTERS.to_vec()
     }, {
         assert_cmd_snapshot!(Command::new(get_cargo_bin(BIN_NAME))
             .arg("pip-compile")
@@ -1244,11 +1240,7 @@ dependencies = ["django==300.1.4"]
     )?;
 
     insta::with_settings!({
-        filters => vec![
-            (r"\d(ms|s)", "[TIME]"),
-            (r"#    .* pip-compile", "#    [BIN_PATH] pip-compile"),
-            (r"--cache-dir .*", "--cache-dir [CACHE_DIR]"),
-        ]
+        filters => INSTA_FILTERS.to_vec()
     }, {
         assert_cmd_snapshot!(Command::new(get_cargo_bin(BIN_NAME))
             .arg("pip-compile")
@@ -1261,3 +1253,92 @@ dependencies = ["django==300.1.4"]
 
     Ok(())
 }
+
+/// Resolve at a specific time in the past
+#[test]
+fn compile_exclude_newer() -> Result<()> {
+    let temp_dir = TempDir::new()?;
+    let cache_dir = TempDir::new()?;
+    let venv = make_venv_py312(&temp_dir, &cache_dir);
+
+    let requirements_in = temp_dir.child("requirements.in");
+    requirements_in.write_str("tqdm")?;
+
+    insta::with_settings!({
+        filters => INSTA_FILTERS.to_vec()
+    }, {
+        assert_cmd_snapshot!(Command::new(get_cargo_bin(BIN_NAME))
+            .arg("pip-compile")
+            .arg("requirements.in")
+            .arg("--exclude-newer")
+            // 4.64.0: 2022-04-04T01:48:46.194635Z1
+            // 4.64.1: 2022-09-03T11:10:27.148080Z
+            .arg("2022-04-04T12:00:00Z")
+            .arg("--cache-dir")
+            .arg(cache_dir.path())
+            .env("VIRTUAL_ENV", venv.as_os_str())
+            .current_dir(&temp_dir), @r###"
+        success: true
+        exit_code: 0
+        ----- stdout -----
+        # This file was autogenerated by Puffin v0.0.1 via the following command:
+        #    puffin pip-compile requirements.in --exclude-newer 2022-04-04T12:00:00Z --cache-dir [CACHE_DIR]
+        tqdm==4.64.0
+
+        ----- stderr -----
+        Resolved 1 package in [TIME]
+        "###);
+    });
+
+    insta::with_settings!({
+        filters => INSTA_FILTERS.to_vec()
+    }, {
+        // Use a date as input instead.
+        // We interpret a date as including this day
+        assert_cmd_snapshot!(Command::new(get_cargo_bin(BIN_NAME))
+            .arg("pip-compile")
+            .arg("requirements.in")
+            .arg("--exclude-newer")
+            .arg("2022-04-04")
+            .arg("--cache-dir")
+            .arg(cache_dir.path())
+            .env("VIRTUAL_ENV", venv.as_os_str())
+            .current_dir(&temp_dir), @r###"
+        success: true
+        exit_code: 0
+        ----- stdout -----
+        # This file was autogenerated by Puffin v0.0.1 via the following command:
+        #    puffin pip-compile requirements.in --exclude-newer 2022-04-04 --cache-dir [CACHE_DIR]
+        tqdm==4.64.0
+
+        ----- stderr -----
+        Resolved 1 package in [TIME]
+        "###);
+        });
+
+    insta::with_settings!({
+        filters => INSTA_FILTERS.to_vec()
+    }, {
+        // Check the error message for invalid datetime
+        assert_cmd_snapshot!(Command::new(get_cargo_bin(BIN_NAME))
+            .arg("pip-compile")
+            .arg("requirements.in")
+            .arg("--exclude-newer")
+            .arg("2022-04-04+02:00")
+            .arg("--cache-dir")
+            .arg(cache_dir.path())
+            .env("VIRTUAL_ENV", venv.as_os_str())
+            .current_dir(&temp_dir), @r###"
+        success: false
+        exit_code: 2
+        ----- stdout -----
+
+        ----- stderr -----
+        error: invalid value '2022-04-04+02:00' for '--exclude-newer <EXCLUDE_NEWER>': Neither a valid date (trailing input) not a valid datetime (input contains invalid characters)
+
+        For more information, try '--help'.
+        "###);
+    });
+
+    Ok(())
+}

crates/puffin-cli/tests/pip_compile.rs

@@ -79,13 +79,16 @@ impl BuildContext for BuildDispatch {
                 self.interpreter_info.simple_version(),
             )?;
             let resolver = Resolver::new(
+                // TODO(konstin): Split settings (for all resolutions) and inputs (only for this
+                // resolution) and attach the former to Self.
                 Manifest::new(
                     requirements.to_vec(),
                     Vec::default(),
                     Vec::default(),
                     ResolutionMode::default(),
                     PreReleaseMode::default(),
                     None, // TODO(zanieb): We may want to provide a project name here
+                    None,
                 ),
                 self.interpreter_info.markers(),
                 &tags,

crates/puffin-dispatch/src/lib.rs

@@ -29,6 +29,7 @@ pypi-types = { path = "../pypi-types" }
 anyhow = { workspace = true }
 bitflags = { workspace = true }
 clap = { workspace = true, features = ["derive"], optional = true }
+chrono = { workspace = true }
 colored = { workspace = true }
 fs-err = { workspace = true, features = ["tokio"] }
 futures = { workspace = true }

crates/puffin-resolver/Cargo.toml

@@ -1,3 +1,4 @@
+use chrono::{DateTime, Utc};
 use pep508_rs::Requirement;
 use puffin_normalize::PackageName;
 
@@ -13,6 +14,7 @@ pub struct Manifest {
     pub(crate) resolution_mode: ResolutionMode,
     pub(crate) prerelease_mode: PreReleaseMode,
     pub(crate) project: Option<PackageName>,
+    pub(crate) exclude_newer: Option<DateTime<Utc>>,
 }
 
 impl Manifest {
@@ -23,6 +25,7 @@ impl Manifest {
         resolution_mode: ResolutionMode,
         prerelease_mode: PreReleaseMode,
         project: Option<PackageName>,
+        exclude_newer: Option<DateTime<Utc>>,
     ) -> Self {
         Self {
             requirements,
@@ -31,6 +34,7 @@ impl Manifest {
             resolution_mode,
             prerelease_mode,
             project,
+            exclude_newer,
         }
     }
 }