{"record":{"id":"bfba474f00de5362","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":"ValueError","httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/expr/list.py","lineNumber":248,"sourceCode":"        >>> df = pl.DataFrame({\"values\": [[1, 2, 3], [4, 5]], \"n\": [2, 1]})\n        >>> df.with_columns(\n        ...     sample=pl.col(\"values\").list.sample(\n        ...         n=pl.col(\"n\"), shuffle=False, seed=1\n        ...     )\n        ... )\n        shape: (2, 3)\n        ┌───────────┬─────┬───────────┐\n        │ values    ┆ n   ┆ sample    │\n        │ ---       ┆ --- ┆ ---       │\n        │ list[i64] ┆ i64 ┆ list[i64] │\n        ╞═══════════╪═════╪═══════════╡\n        │ [1, 2, 3] ┆ 2   ┆ [2, 3]    │\n        │ [4, 5]    ┆ 1   ┆ [5]       │\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 fraction is not None:\n            fraction_pyexpr = parse_into_expression(fraction)\n            return wrap_expr(\n                self._pyexpr.list_sample_fraction(\n                    fraction_pyexpr, with_replacement, shuffle, seed\n                )\n            )\n\n        if n is None:\n            n = 1\n        n_pyexpr = parse_into_expression(n)\n        return wrap_expr(\n            self._pyexpr.list_sample_n(n_pyexpr, with_replacement, shuffle, seed)\n        )\n\n    def sum(self) -> Expr:\n        \"\"\"","sourceCodeStart":230,"sourceCodeEnd":266,"githubUrl":"https://github.com/pola-rs/polars/blob/fe841f959ef4d2ceefc05a310d33ed7b1ab24e5e/py-polars/src/polars/expr/list.py#L230-L266","documentation":"Parameter-exclusivity error from list.sample: the sample size can be specified either as an absolute count (`n`) or as a relative `fraction` of the list, never both. Supplying both makes the intended sample size ambiguous, so the guard rejects the call before any sampling happens.","triggerScenarios":"Calling pl.col('l').list.sample(n=2, fraction=0.5) with both arguments non-None; calling sample(2, 0.5) positionally.","commonSituations":"Config exposing both 'count' and 'percentage' fields that are both set; copying a call and adding a fraction without removing n; generic wrapper functions forwarding both options.","solutions":["Pass only n OR only fraction, setting the other to None","Compute n from fraction at the call site if you know the list length","Normalize in wrapper code: if fraction is not None: use fraction else use n","Validate config so exactly one of count/percentage is set"],"exampleFix":"// before\npl.col('l').list.sample(n=2, fraction=0.5)\n// after\npl.col('l').list.sample(fraction=0.5)","handlingStrategy":"validation","validationCode":"if (n is not None) == (fraction is not None):\n    raise ValueError('specify exactly one of n or fraction')","typeGuard":null,"tryCatchPattern":"try:\n    e = col.list.sample(n=n, fraction=fraction)\nexcept ValueError as e:\n    if 'both `n` and `fraction`' in str(e):\n        e = col.list.sample(n=n if n is not None else None,\n                            fraction=None if n is not None else fraction)\n    else:\n        raise","preventionTips":["Enforce n XOR fraction in your own API wrapper","Reject configs that set both count and percentage","Default one parameter to None and document the exclusivity"],"tags":["python","polars","value-error","lists","sampling"],"backgroundTag":"mutually-exclusive-options","analyzedSha":"fe841f959ef4d2ceefc05a310d33ed7b1ab24e5e","analyzedAt":"2026-09-18T22:14:11.667Z","contentChangedAt":"2026-09-18T22:14:11.667Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}