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 Parameters 

38 ---------- 

39 path : str or Path 

40 File path. 

41 usecols : list-like, optional 

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

43 convert_categoricals : bool, default is True 

44 Convert categorical columns into pd.Categorical. 

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

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

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

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

49 is as follows: 

50 

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

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

53 nullable :class:`ArrowDtype` :class:`DataFrame` 

54 

55 .. versionadded:: 2.0 

56 **kwargs 

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

58 

59 .. versionadded:: 3.0 

60 

61 Returns 

62 ------- 

63 DataFrame 

64 DataFrame based on the SPSS file. 

65 

66 See Also 

67 -------- 

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

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

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

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

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

73 

74 Examples 

75 -------- 

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

77 """ 

78 pyreadstat = import_optional_dependency("pyreadstat") 

79 check_dtype_backend(dtype_backend) 

80 

81 if usecols is not None: 

82 if not is_list_like(usecols): 

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

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

85 

86 df, metadata = pyreadstat.read_sav( 

87 stringify_path(path), 

88 usecols=usecols, 

89 apply_value_formats=convert_categoricals, 

90 **kwargs, 

91 ) 

92 df.attrs = metadata.__dict__ 

93 if dtype_backend is not lib.no_default: 

94 df = df.convert_dtypes(dtype_backend=dtype_backend) 

95 return df