Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.9/dist-packages/pandas/io/spss.py: 38%

1from __future__ import annotations 

2 

3from typing import TYPE_CHECKING 

4 

5from pandas._libs import lib 

6from pandas.compat._optional import import_optional_dependency 

7from pandas.util._validators import check_dtype_backend 

8 

9from pandas.core.dtypes.inference import is_list_like 

10 

11from pandas.io.common import stringify_path 

12 

13if TYPE_CHECKING: 

14 from collections.abc import Sequence 

15 from pathlib import Path 

16 

17 from pandas._typing import DtypeBackend 

18 

19 from pandas import DataFrame 

20 

21 

22def read_spss( 

23 path: str | Path, 

24 usecols: Sequence[str] | None = None, 

25 convert_categoricals: bool = True, 

26 dtype_backend: DtypeBackend | lib.NoDefault = lib.no_default, 

27) -> DataFrame: 

28 """ 

29 Load an SPSS file from the file path, returning a DataFrame. 

30 

31 Parameters 

32 ---------- 

33 path : str or Path 

34 File path. 

35 usecols : list-like, optional 

36 Return a subset of the columns. If None, return all columns. 

37 convert_categoricals : bool, default is True 

38 Convert categorical columns into pd.Categorical. 

39 dtype_backend : {'numpy_nullable', 'pyarrow'}, default 'numpy_nullable' 

40 Back-end data type applied to the resultant :class:`DataFrame` 

41 (still experimental). Behaviour is as follows: 

42 

43 * ``"numpy_nullable"``: returns nullable-dtype-backed :class:`DataFrame` 

44 (default). 

45 * ``"pyarrow"``: returns pyarrow-backed nullable :class:`ArrowDtype` 

46 DataFrame. 

47 

48 .. versionadded:: 2.0 

49 

50 Returns 

51 ------- 

52 DataFrame 

53 

54 Examples 

55 -------- 

56 >>> df = pd.read_spss("spss_data.sav") # doctest: +SKIP 

57 """ 

58 pyreadstat = import_optional_dependency("pyreadstat") 

59 check_dtype_backend(dtype_backend) 

60 

61 if usecols is not None: 

62 if not is_list_like(usecols): 

63 raise TypeError("usecols must be list-like.") 

64 usecols = list(usecols) # pyreadstat requires a list 

65 

66 df, metadata = pyreadstat.read_sav( 

67 stringify_path(path), usecols=usecols, apply_value_formats=convert_categoricals 

68 ) 

69 df.attrs = metadata.__dict__ 

70 if dtype_backend is not lib.no_default: 

71 df = df.convert_dtypes(dtype_backend=dtype_backend) 

72 return df