From b66d8e8a40f17625b783188c841a57bbbdcc106b Mon Sep 17 00:00:00 2001
From: Raphael Krupinski <rafalkrupinski@users.noreply.github.com>
Date: Mon, 29 May 2023 07:31:51 +0200
Subject: [PATCH] chore(DX): add type hints to Document, BaseDocument and
 get_doc (#21060)

* chore: add type hints to Document, BaseDocument and get_doc

* refactor: better type hints

get_doc has multiple ways to use it, added all known ways

---------

Co-authored-by: Raphael Krupinski <10319569-mattesilver@users.noreply.gitlab.com>
Co-authored-by: Ankush Menat <ankush@frappe.io>
---
 frappe/__init__.py | 39 +++++++++++++++++++++++++++++++++++++--
 1 file changed, 37 insertions(+), 2 deletions(-)

diff --git a/frappe/__init__.py b/frappe/__init__.py
index 5a03438a9e..5efdfd8ce9 100644
--- a/frappe/__init__.py
+++ b/frappe/__init__.py
@@ -17,7 +17,7 @@ import json
 import os
 import re
 import warnings
-from typing import TYPE_CHECKING, Any, Callable, Literal, Optional, overload
+from typing import TYPE_CHECKING, Any, Callable, Literal, Optional, TypeAlias, overload
 
 import click
 from werkzeug.local import Local, release_local
@@ -1142,7 +1142,42 @@ def get_cached_value(
 	return values
 
 
-def get_doc(*args, **kwargs) -> "Document":
+_SingleDocument: TypeAlias = "Document"
+_NewDocument: TypeAlias = "Document"
+
+
+@overload
+def get_doc(document: "Document", /) -> "Document":
+	pass
+
+
+@overload
+def get_doc(doctype: str, /) -> _SingleDocument:
+	"""Retrieve Single DocType from DB, doctype must be positional argument."""
+	pass
+
+
+@overload
+def get_doc(doctype: str, name: str, /, for_update: bool | None = None) -> "Document":
+	"""Retrieve DocType from DB, doctype and name must be positional argument."""
+	pass
+
+
+@overload
+def get_doc(**kwargs: dict) -> "_NewDocument":
+	"""Initialize document from kwargs.
+	Not recommended. Use `frappe.new_doc` instead."""
+	pass
+
+
+@overload
+def get_doc(documentdict: dict) -> "_NewDocument":
+	"""Create document from dict.
+	Not recommended. Use `frappe.new_doc` instead."""
+	pass
+
+
+def get_doc(*args, **kwargs):
 	"""Return a `frappe.model.document.Document` object of the given type and name.
 
 	:param arg1: DocType name as string **or** document JSON.