Support LiteralString

Author: cpburnz

Makefile

@@ -57,9 +57,9 @@ dev-venv-base:
 dev-venv-create: dev-venv-base dev-venv-install
 
 dev-venv-install:
-	${VENV} pip install --upgrade pip setuptools wheel
-	${VENV} pip install --upgrade build sphinx tox twine
-	${VENV} pip install -e "${SRC_DIR}"
+	${VENV} pip3 install --upgrade pip setuptools wheel
+	${VENV} pip3 install --upgrade build sphinx tox twine typing-extensions
+	${VENV} pip3 install -e "${SRC_DIR}"
 
 
 ################################################################################

sqlparams/__init__.py

@@ -6,7 +6,6 @@
 import re
 from typing import (
 	Any,
-	AnyStr,
 	Dict,
 	Iterable,
 	List,
@@ -26,8 +25,9 @@
 	__copyright__,
 	__credits__,
 	__license__,
-	__version__,
-)
+	__version__)
+from ._util import (
+	SqlStr)
 
 _BYTES_ENCODING = 'latin1'
 """
@@ -471,14 +471,15 @@ def expand_tuples(self) -> bool:
 
 	def format(
 		self,
-		sql: AnyStr,
+		sql: SqlStr,
 		params: Union[Dict[Union[str, int], Any], Sequence[Any]],
-	) -> Tuple[AnyStr, Union[Dict[Union[str, int], Any], Sequence[Any]]]:
+	) -> Tuple[SqlStr, Union[Dict[str, Any], Sequence[Any]]]:
 		"""
 		Convert the SQL query to use the out-style parameters instead of
 		the in-style parameters.
 
-		*sql* (:class:`str` or :class:`bytes`) is the SQL query.
+		*sql* (:class:`LiteralString`, :class:`str`, or :class:`bytes`) is
+		the SQL query.
 
 		*params* (:class:`~collections.abc.Mapping` or :class:`~collections.abc.Sequence`)
 		contains the set of in-style parameters. It maps each parameter
@@ -489,7 +490,8 @@ def format(
 
 		Returns a :class:`tuple` containing:
 
-		-	The formatted SQL query (:class:`str` or :class:`bytes`).
+		-	The formatted SQL query (:class:`LiteralString`, :class:`str` or
+			:class:`bytes`).
 
 		-	The set of converted out-style parameters (:class:`dict` or
 			:class:`list`).
@@ -521,14 +523,15 @@ def format(
 
 	def formatmany(
 		self,
-		sql: AnyStr,
+		sql: SqlStr,
 		many_params: Union[Iterable[Dict[Union[str, int], Any]], Iterable[Sequence[Any]]],
-	) -> Tuple[AnyStr, Union[List[Dict[Union[str, int], Any]], List[Sequence[Any]]]]:
+	) -> Tuple[SqlStr, Union[List[Dict[str, Any]], List[Sequence[Any]]]]:
 		"""
 		Convert the SQL query to use the out-style parameters instead of the
 		in-style parameters.
 
-		*sql* (:class:`str` or :class:`bytes`) is the SQL query.
+		*sql* (:class:`LiteralString`, :class:`str` or :class:`bytes`) is
+		the SQL query.
 
 		*many_params* (:class:`~collections.abc.Iterable`) contains each set
 		of in-style parameters (*params*).
@@ -542,7 +545,8 @@ def formatmany(
 
 		Returns a :class:`tuple` containing:
 
-		-	The formatted SQL query (:class:`str` or :class:`bytes`).
+		-	The formatted SQL query (:class:`LiteralString`, :class:`str` or
+			:class:`bytes`).
 
 		-	A :class:`list` containing each set of converted out-style
 			parameters (:class:`dict` or :class:`list`).

sqlparams/_converting.py

@@ -79,7 +79,7 @@ def convert(
 		self,
 		sql: str,
 		params: Union[Dict[Union[str, int], Any], Sequence[Any]],
-	) -> Tuple[str, Union[Dict[Union[str, int], Any], Sequence[Any]]]:
+	) -> Tuple[str, Union[Dict[str, Any], Sequence[Any]]]:
 		"""
 		Convert the SQL query to use the named out-style parameters from the
 		named the in-style parameters.

sqlparams/_meta.py

@@ -3,7 +3,7 @@
 """
 
 __author__ = "Caleb P. Burns"
-__copyright__ = "Copyright © 2012-2022 by Caleb P. Burns"
+__copyright__ = "Copyright © 2012-2023 by Caleb P. Burns"
 __credits__ = [
 	"khomyakov42 <https://github.com/khomyakov42>",
 	"pedermoller <https://github.com/pedermoller>",
@@ -14,4 +14,4 @@
 	"sergey-shambir <https://github.com/sergey-shambir>",
 ]
 __license__ = "MIT License"
-__version__ = "5.0.0"
+__version__ = "5.1.0.dev1"

sqlparams/_util.py

@@ -2,7 +2,26 @@
 This module defines internal utility methods.
 """
 
-from collections.abc import Iterable, Sequence
+from collections.abc import (
+	Iterable,
+	Sequence)
+from typing import (
+	TypeVar)
+
+# LiteralString: Python 3.11+
+try:
+	from typing import LiteralString
+except ImportError:
+	try:
+		from typing_extensions import LiteralString
+	except ImportError:
+		LiteralString = str
+
+SqlStr = TypeVar('SqlStr', LiteralString, str, bytes)
+"""
+Constrained type variable for SQL strings (:class:`LiteralString`,
+:class:`str`, :class:`bytes`).
+"""
 
 
 def is_iterable(value):