"""Functions to perform parsing and conversion in one step."""
from __future__ import annotations
from typing import TYPE_CHECKING, Any
from .conversion._conversion import DEFAULT_CLASS_MAP, ConstructorDict, convert
from .parser._parser import (
DEFAULT_ALTREP_MAP,
AcceptableFile,
AltRepConstructorMap,
Traversable,
parse_file,
)
if TYPE_CHECKING:
import os
from collections.abc import MutableMapping
def read_rdata( # noqa: PLR0913
file_or_path: AcceptableFile | os.PathLike[Any] | Traversable | str,
*,
expand_altrep: bool = True,
altrep_constructor_dict: AltRepConstructorMap = DEFAULT_ALTREP_MAP,
extension: str | None = None,
constructor_dict: ConstructorDict = DEFAULT_CLASS_MAP,
default_encoding: str | None = None,
force_default_encoding: bool = False,
global_environment: MutableMapping[str, Any] | None = None,
base_environment: MutableMapping[str, Any] | None = None,
) -> Any: # noqa: ANN401
parsed = parse_file(
file_or_path=file_or_path,
expand_altrep=expand_altrep,
altrep_constructor_dict=altrep_constructor_dict,
extension=extension,
)
return convert(
parsed,
constructor_dict=constructor_dict,
default_encoding=default_encoding,
force_default_encoding=force_default_encoding,
global_environment=global_environment,
base_environment=base_environment,
)
[docs]
def read_rds( # noqa: PLR0913
file_or_path: AcceptableFile | os.PathLike[Any] | Traversable | str,
*,
expand_altrep: bool = True,
altrep_constructor_dict: AltRepConstructorMap = DEFAULT_ALTREP_MAP,
constructor_dict: ConstructorDict = DEFAULT_CLASS_MAP,
default_encoding: str | None = None,
force_default_encoding: bool = False,
global_environment: MutableMapping[str, Any] | None = None,
base_environment: MutableMapping[str, Any] | None = None,
) -> Any: # noqa: ANN401
"""
Read an RDS file, containing an R object.
This is a convenience function that wraps :func:`rdata.parser.parse_file`
and :func:`rdata.parser.convert`, as it is the common use case.
Args:
file_or_path: File in the RDS format.
expand_altrep: Whether to translate ALTREPs to normal objects.
altrep_constructor_dict: Dictionary mapping each ALTREP to
its constructor.
constructor_dict: Dictionary mapping names of R classes to constructor
functions with the following prototype:
.. code-block :: python
def constructor(obj, attrs):
...
This dictionary can be used to support custom R classes. By
default, the dictionary used is
:data:`~rdata.conversion._conversion.DEFAULT_CLASS_MAP`
which has support for several common classes.
default_encoding: Default encoding used for strings with unknown
encoding. If `None`, the one stored in the file will be used, or
ASCII as a fallback.
force_default_encoding:
Use the default encoding even if the strings specify other
encoding.
global_environment: Global environment to use. By default is an empty
environment.
base_environment: Base environment to use. By default is an empty
environment.
Returns:
Contents of the file converted to a Python object.
See Also:
:func:`read_rda`: Similar function that parses a RDA or RDATA file.
Examples:
Parse one of the included examples, containing a dataframe
>>> import rdata
>>>
>>> data = rdata.read_rds(
... rdata.TESTDATA_PATH / "test_dataframe.rds"
... )
>>> data
class value
1 a 1
2 b 2
3 b 3
"""
return read_rdata(
file_or_path=file_or_path,
expand_altrep=expand_altrep,
altrep_constructor_dict=altrep_constructor_dict,
extension=".rds",
constructor_dict=constructor_dict,
default_encoding=default_encoding,
force_default_encoding=force_default_encoding,
global_environment=global_environment,
base_environment=base_environment,
)
[docs]
def read_rda( # noqa: PLR0913
file_or_path: AcceptableFile | os.PathLike[Any] | Traversable | str,
*,
expand_altrep: bool = True,
altrep_constructor_dict: AltRepConstructorMap = DEFAULT_ALTREP_MAP,
constructor_dict: ConstructorDict = DEFAULT_CLASS_MAP,
default_encoding: str | None = None,
force_default_encoding: bool = False,
global_environment: MutableMapping[str, Any] | None = None,
base_environment: MutableMapping[str, Any] | None = None,
) -> dict[str, Any]:
"""
Read an RDA or RDATA file, containing an R object.
This is a convenience function that wraps :func:`rdata.parser.parse_file`
and :func:`rdata.parser.convert`, as it is the common use case.
Args:
file_or_path: File in the RDA format.
expand_altrep: Whether to translate ALTREPs to normal objects.
altrep_constructor_dict: Dictionary mapping each ALTREP to
its constructor.
constructor_dict: Dictionary mapping names of R classes to constructor
functions with the following prototype:
.. code-block :: python
def constructor(obj, attrs):
...
This dictionary can be used to support custom R classes. By
default, the dictionary used is
:data:`~rdata.conversion._conversion.DEFAULT_CLASS_MAP`
which has support for several common classes.
default_encoding: Default encoding used for strings with unknown
encoding. If `None`, the one stored in the file will be used, or
ASCII as a fallback.
force_default_encoding:
Use the default encoding even if the strings specify other
encoding.
global_environment: Global environment to use. By default is an empty
environment.
base_environment: Base environment to use. By default is an empty
environment.
Returns:
Contents of the file converted to a Python object.
See Also:
:func:`read_rds`: Similar function that parses a RDS file.
Examples:
Parse one of the included examples, containing a dataframe
>>> import rdata
>>>
>>> data = rdata.read_rda(
... rdata.TESTDATA_PATH / "test_dataframe.rda"
... )
>>> data
{'test_dataframe': class value
1 a 1
2 b 2
3 b 3}
"""
return read_rdata( # type: ignore[no-any-return]
file_or_path=file_or_path,
expand_altrep=expand_altrep,
altrep_constructor_dict=altrep_constructor_dict,
extension=".rda",
constructor_dict=constructor_dict,
default_encoding=default_encoding,
force_default_encoding=force_default_encoding,
global_environment=global_environment,
base_environment=base_environment,
)
