{"record":{"id":"88c09c76c49a1341","repo":"pola-rs/polars","slug":"cannot-specify-both-n-and-fraction","errorCode":null,"errorMessage":"cannot specify both `n` and `fraction`","messagePattern":"cannot specify both `n` and `fraction`","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/dataframe/frame.py","lineNumber":11653,"sourceCode":"        ...         \"foo\": [1, 2, 3],\n        ...         \"bar\": [6, 7, 8],\n        ...         \"ham\": [\"a\", \"b\", \"c\"],\n        ...     }\n        ... )\n        >>> df.sample(n=2, shuffle=False, seed=0)  # doctest: +IGNORE_RESULT\n        shape: (2, 3)\n        ┌─────┬─────┬─────┐\n        │ foo ┆ bar ┆ ham │\n        │ --- ┆ --- ┆ --- │\n        │ i64 ┆ i64 ┆ str │\n        ╞═════╪═════╪═════╡\n        │ 3   ┆ 8   ┆ c   │\n        │ 2   ┆ 7   ┆ b   │\n        └─────┴─────┴─────┘\n        \"\"\"\n        if n is not None and fraction is not None:\n            msg = \"cannot specify both `n` and `fraction`\"\n            raise ValueError(msg)\n\n        if n is None and fraction is not None:\n            if not isinstance(fraction, pl.Series):\n                fraction = pl.Series(\"frac\", [fraction])\n\n            return self._from_pydf(\n                self._df.sample_frac(fraction._s, with_replacement, shuffle, seed)\n            )\n\n        if n is None:\n            n = 1\n\n        if not isinstance(n, pl.Series):\n            n = pl.Series(\"\", [n])\n\n        return self._from_pydf(self._df.sample_n(n._s, with_replacement, shuffle, seed))\n\n    def fold(self, operation: Callable[[Series, Series], Series]) -> Series:","sourceCodeStart":11635,"sourceCodeEnd":11671,"githubUrl":"https://github.com/pola-rs/polars/blob/df599052daf96e7a9cc30a3b0c6bd25d6947e3c0/py-polars/src/polars/dataframe/frame.py#L11635-L11671","documentation":"DataFrame.sample draws rows either by absolute count (`n`) or by a fraction of rows (`fraction`); the two parameters are mutually exclusive and both default to None. Passing non-None values for both raises ValueError immediately, before any sampling happens, because the intended sample size would be ambiguous.","triggerScenarios":"df.sample(n=10, fraction=0.5); generic wrappers that expose both knobs and forward both, e.g. def take(df, n=5, frac=0.2): return df.sample(n=n, fraction=frac); refactor added fraction but left the n call site in place.","commonSituations":"Reusable sampling helpers with defaulted n and fraction parameters that are both non-None at the call site; A/B experiment code switching between count-based and ratio-based sampling; splatting an options dict containing both keys.","solutions":["Pass exactly one of n or fraction and leave the other as None (or omit it)","In wrappers, resolve the conflict first: use fraction if frac is not None else n","When splatting option dicts, drop the unused key: opts.pop('n', None) or opts.pop('fraction', None)"],"exampleFix":"# before\nsampled = df.sample(n=100, fraction=0.1)\n\n# after\nsampled = df.sample(n=100)\n# or\nsampled = df.sample(fraction=0.1)","handlingStrategy":"validation","validationCode":"if n is not None and fraction is not None:\n    raise ValueError('pass exactly one of n / fraction')\nsampled = df.sample(n=n, fraction=fraction)","typeGuard":null,"tryCatchPattern":null,"preventionTips":["In sampling wrappers, default both to None and resolve to exactly one before calling","Prefer fraction for proportional sampling and n for absolute — do not expose both as non-None defaults","When splatting option dicts, pop the key you are not using"],"tags":["polars","dataframe","sample","mutually-exclusive-parameters","valueerror"],"backgroundTag":null,"analyzedSha":"df599052daf96e7a9cc30a3b0c6bd25d6947e3c0","analyzedAt":"2026-08-16T12:10:03.978Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}