Use Unix newlines when

Author: domdfcoding

domdf_python_tools/paths.py

@@ -40,11 +40,10 @@
 import pathlib
 import shutil
 import stat
-import types
 from typing import IO, Any, Callable, Iterable, List, Optional
 
 # this package
-from domdf_python_tools.typing import PathLike
+from domdf_python_tools.typing import JsonLibrary, PathLike
 
 __all__ = [
 		"append",
@@ -62,6 +61,8 @@
 		"WindowsPathPlus",
 		]
 
+newline_default = object()
+
 
 def append(var: str, filename: PathLike, **kwargs) -> int:
 	"""
@@ -297,6 +298,10 @@ class PathPlus(pathlib.Path):
 	but cannot instantiate a WindowsPath on a POSIX system or vice versa.
 
 	.. versionadded:: 0.3.8
+
+	.. versionchanged:: 0.5.1
+
+		Defaults to Unix line endings (``LF``) on all platforms.
 	"""
 
 	def __new__(cls, *args, **kwargs):
@@ -471,53 +476,67 @@ def open(
 			buffering: int = -1,
 			encoding: Optional[str] = "UTF-8",
 			errors: Optional[str] = None,
-			newline: Optional[str] = None,
+			newline: Optional[str] = newline_default,  # type: ignore
 			) -> IO[Any]:
 		"""
 		Open the file pointed by this path and return a file object, as
 		the built-in open() function does.
 
 		:param mode: The mode to open the file in.
-		:default mode: ``"r"`` (read only)
+		:default mode: ``'r'`` (read only)
 		:type mode: str
 		:param buffering:
 		:type buffering: int
 		:param encoding:
 		:type encoding: str
 		:param errors:
 		:param newline:
+		:default newline: `universal newlines <https://docs.python.org/3/glossary.html#term-universal-newlines>`__ for reading, Unix line endings (``LF``) for writing.
 
 		:return:
 
 		.. versionadded:: 0.3.8
+
+		.. versionchanged:: 0.5.1
+
+			Defaults to Unix line endings (``LF``) on all platforms.
 		"""
 
 		if 'b' in mode:
 			encoding = None
+			newline = None
+
+		if newline is newline_default:
+			if 'r' in mode:
+				newline = None
+			else:
+				newline = "\n"
+
 		return super().open(mode, buffering=buffering, encoding=encoding, errors=errors, newline=newline)
 
 	def dump_json(
 			self,
 			data: Any,
 			encoding: Optional[str] = "UTF-8",
 			errors: Optional[str] = None,
-			json_library: types.ModuleType = json,
+			json_library: JsonLibrary = json,  # type: ignore
 			**kwargs,
 			) -> int:
 		"""
-		Dump ``data`` to the file.
+		Dump ``data`` to the file as JSON.
 
 		:param data: The object to serialise to JSON.
 		:param encoding: The encoding to write to the file using.
 		:param errors:
 		:param json_library: The JSON serialisation library to use.
+		:default json_library: :mod:`json`
 		:param kwargs: Keyword arguments to pass to the JSON serialisation function.
 
 		.. versionadded:: 0.5.0
 		"""
 
 		return self.write_text(
-				json_library.dumps(data, **kwargs),  # type: ignore
+				json_library.dumps(data, **kwargs),
 				encoding=encoding,
 				errors=errors,
 				)
@@ -526,7 +545,7 @@ def load_json(
 			self,
 			encoding: Optional[str] = "UTF-8",
 			errors: Optional[str] = None,
-			json_library: types.ModuleType = json,
+			json_library: JsonLibrary = json,  # type: ignore
 			**kwargs,
 			) -> Any:
 		"""
@@ -535,14 +554,15 @@ def load_json(
 		:param encoding: The encoding to write to the file using.
 		:param errors:
 		:param json_library: The JSON serialisation library to use.
+		:default json_library: :mod:`json`
 		:param kwargs: Keyword arguments to pass to the JSON deserialisation function.
 
 		:return: The deserialised JSON data.
 
 		.. versionadded:: 0.5.0
 		"""
 
-		return json_library.loads(  # type: ignore
+		return json_library.loads(
 				self.read_text(encoding=encoding, errors=errors),
 				**kwargs,
 				)

domdf_python_tools/typing.py

@@ -26,10 +26,13 @@
 # stdlib
 import os
 import pathlib
+import sys
 from decimal import Decimal
-from typing import Any, Type, Union
+from json import JSONDecoder, JSONEncoder
+from types import ModuleType
+from typing import Any, Callable, Dict, List, Optional, Tuple, Type, Union
 
-__all__ = ["PathLike", "AnyNumber", "check_membership"]
+__all__ = ["PathLike", "AnyNumber", "check_membership", "JsonLibrary"]
 
 #: Type hint for objects that represent filesystem paths.
 PathLike = Union[str, pathlib.Path, os.PathLike]
@@ -46,7 +49,7 @@
 
 def check_membership(obj: Any, type_: Union[Type, object]) -> bool:
 	"""
-	Check if the type of ``obj`` is one of the types in a :py:data:`typing.Union`, :typing.sequence:``Sequence`` etc.
+	Check if the type of ``obj`` is one of the types in a :py:data:`typing.Union`, :typing.sequence:`Sequence` etc.
 
 	:param obj: The object to check the type of
 	:param type_: A :class:`~typing.Type` that has members, such as a List, Union or Sequence.
@@ -56,3 +59,72 @@ def check_membership(obj: Any, type_: Union[Type, object]) -> bool:
 	"""
 
 	return isinstance(obj, type_.__args__)  # type: ignore
+
+
+class JsonLibrary(ModuleType):
+	"""
+	Type hint for functions that take a JSON serialisation-deserialisation library as an argument.
+
+	The library implement at least the following methods:
+	"""
+
+	@staticmethod
+	def dumps(
+			obj: Any,
+			*,
+			skipkeys: bool = ...,
+			ensure_ascii: bool = ...,
+			check_circular: bool = ...,
+			allow_nan: bool = ...,
+			cls: Optional[Type[JSONEncoder]] = ...,
+			indent: Union[None, int, str] = ...,
+			separators: Optional[Tuple[str, str]] = ...,
+			default: Optional[Callable[[Any], Any]] = ...,
+			sort_keys: bool = ...,
+			**kwds: Any,
+			) -> str:
+		"""
+		Serialize ``obj`` to a JSON formatted ``str``.
+
+		:param obj:
+		:param skipkeys:
+		:param ensure_ascii:
+		:param check_circular:
+		:param allow_nan:
+		:param cls:
+		:param indent:
+		:param separators:
+		:param default:
+		:param sort_keys:
+		:param kwds:
+		"""
+
+	if sys.version_info >= (3, 6):
+		_LoadsString = Union[str, bytes]
+	else:
+		_LoadsString = str
+
+	@staticmethod
+	def loads(
+			s: _LoadsString,
+			*,
+			cls: Optional[Type[JSONDecoder]] = ...,
+			object_hook: Optional[Callable[[Dict[Any, Any]], Any]] = ...,
+			parse_float: Optional[Callable[[str], Any]] = ...,
+			parse_int: Optional[Callable[[str], Any]] = ...,
+			parse_constant: Optional[Callable[[str], Any]] = ...,
+			object_pairs_hook: Optional[Callable[[List[Tuple[Any, Any]]], Any]] = ...,
+			**kwds: Any,
+			) -> Any:
+		"""
+		Deserialize ``s`` to a Python object.
+
+		:param s:
+		:param cls:
+		:param object_hook:
+		:param parse_float:
+		:param parse_int:
+		:param parse_constant:
+		:param object_pairs_hook:
+		:param kwds:
+		"""