Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.11/site-packages/pandas/io/spss.py: 42%

1from __future__ import annotations 

2 

3from typing import ( 

4 TYPE_CHECKING, 

5 Any, 

6) 

7 

8from pandas._libs import lib 

9from pandas.compat._optional import import_optional_dependency 

10from pandas.util._decorators import set_module 

11from pandas.util._validators import check_dtype_backend 

12 

13from pandas.core.dtypes.inference import is_list_like 

14 

15from pandas.io.common import stringify_path 

16 

17if TYPE_CHECKING: 

18 from collections.abc import Sequence 

19 from pathlib import Path 

20 

21 from pandas._typing import DtypeBackend 

22 

23 from pandas import DataFrame 

24 

25 

26@set_module("pandas") 

27def read_spss( 

28 path: str | Path, 

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

30 convert_categoricals: bool = True, 

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

32 **kwargs: Any, 

33) -> DataFrame: 

34 """ 

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

36 

37 This function reads data saved in the SPSS ``.sav`` format using the 

38 ``pyreadstat`` library, which must be installed separately. 

39 

40 Parameters 

41 ---------- 

42 path : str or Path 

43 File path. 

44 usecols : list-like, optional 

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

46 convert_categoricals : bool, default is True 

47 Convert categorical columns into pd.Categorical. 

48 dtype_backend : {'numpy_nullable', 'pyarrow'} 

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

50 (still experimental). If not specified, the default behavior 

51 is to not use nullable data types. If specified, the behavior 

52 is as follows: 

53 

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

55 * ``"pyarrow"``: returns pyarrow-backed 

56 nullable :class:`ArrowDtype` :class:`DataFrame` 

57 

58 .. versionadded:: 2.0 

59 **kwargs 

60 Additional keyword arguments that can be passed to :func:`pyreadstat.read_sav`. 

61 

62 .. versionadded:: 3.0 

63 

64 Returns 

65 ------- 

66 DataFrame 

67 DataFrame based on the SPSS file. 

68 

69 See Also 

70 -------- 

71 read_csv : Read a comma-separated values (csv) file into a pandas DataFrame. 

72 read_excel : Read an Excel file into a pandas DataFrame. 

73 read_sas : Read an SAS file into a pandas DataFrame. 

74 read_orc : Load an ORC object into a pandas DataFrame. 

75 read_feather : Load a feather-format object into a pandas DataFrame. 

76 

77 Examples 

78 -------- 

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

80 """ 

81 pyreadstat = import_optional_dependency("pyreadstat") 

82 check_dtype_backend(dtype_backend) 

83 

84 if usecols is not None: 

85 if not is_list_like(usecols): 

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

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

88 

89 df, metadata = pyreadstat.read_sav( 

90 stringify_path(path), 

91 usecols=usecols, 

92 apply_value_formats=convert_categoricals, 

93 **kwargs, 

94 ) 

95 df.attrs = metadata.__dict__ 

96 if dtype_backend is not lib.no_default: 

97 df = df.convert_dtypes(dtype_backend=dtype_backend) 

98 return df