From 7450c262bde2afc5b15d1e696abce6c71ab54593 Mon Sep 17 00:00:00 2001
From: andrecs <12188364+andrecsilva@users.noreply.github.com>
Date: Thu, 21 Dec 2023 08:57:41 -0300
Subject: [PATCH] Documentation for literal-or-new-object-identity

---
 src/codemodder/scripts/generate_docs.py                  | 4 ++++
 .../docs/pixee_python_literal-or-new-object-identity.md  | 9 +++++++++
 src/core_codemods/literal_or_new_object_identity.py      | 2 +-
 3 files changed, 14 insertions(+), 1 deletion(-)
 create mode 100644 src/core_codemods/docs/pixee_python_literal-or-new-object-identity.md

diff --git a/src/codemodder/scripts/generate_docs.py b/src/codemodder/scripts/generate_docs.py
index 1786b03e..e2e77fb6 100644
--- a/src/codemodder/scripts/generate_docs.py
+++ b/src/codemodder/scripts/generate_docs.py
@@ -174,6 +174,10 @@ class DocMetadata:
         importance="Low",
         guidance_explained="Removing future imports is safe and will not cause any issues.",
     ),
+    "literal-or-new-object-identity": DocMetadata(
+        importance="Low",
+        guidance_explained="Since literals and new objects have their own identities, comparisons against them using `is` operators are most likely a bug and thus we deem the change safe.",
+    ),
 }
 
 
diff --git a/src/core_codemods/docs/pixee_python_literal-or-new-object-identity.md b/src/core_codemods/docs/pixee_python_literal-or-new-object-identity.md
new file mode 100644
index 00000000..0c017f11
--- /dev/null
+++ b/src/core_codemods/docs/pixee_python_literal-or-new-object-identity.md
@@ -0,0 +1,9 @@
+The `is` and `is not` operator will only return `True` when the expression have the same `id`, that is, `a is b` is equivalent to `id(a) == id(b)`. New objects and literals have their own identities and thus shouldn't be compared with using the `is` or `is not` operators.
+
+Our changes look something like this:
+
+```diff
+def foo(l):
+-    return l is [1,2,3]
++    return l == [1,2,3]
+```
diff --git a/src/core_codemods/literal_or_new_object_identity.py b/src/core_codemods/literal_or_new_object_identity.py
index ecc314d5..fe98b157 100644
--- a/src/core_codemods/literal_or_new_object_identity.py
+++ b/src/core_codemods/literal_or_new_object_identity.py
@@ -12,7 +12,7 @@ class LiteralOrNewObjectIdentity(BaseCodemod, NameResolutionMixin):
     DESCRIPTION = SUMMARY
     REFERENCES = [
         {
-            "url": "https://docs.python.org/3/library/operator.html#operator.is_",
+            "url": "https://docs.python.org/3/library/stdtypes.html#comparisons",
             "description": "",
         },
     ]