In Python, when to modify self and when to return new instance?

I am very often in a great dilemma, when should a class modify itself and when to return a new modified instance.

Lets say I want to program a simple sequence library.

class Seq:
   def __init__(self, seq):
      self.seq = seq

and then I want to rename the elements in the sequence, there are two options for this method in Seq:

def rename(lookup):
   self.seq = [lookup[e] for e in self.seq]

or

def rename(lookup):
   return Seq([lookup[e] for e in self.seq])

I will be dealing with more complicated structures, for exampke, if I am creating a graph and I want to put it into unique canonical (unique vertex enumeration) form, should it put itself in this form or return a new instance. What are most common practices about this and when to choose the two options?

My thinking is this: you have to participate what the users will have most use of. But is this

def rename(lookup, create_new_instance = False):
   if create_new_instance:
      return [lookup[e] for e in self.seq]
   else:
      self.seq = [lookup[e] for e in self.seq]

a good practice?

Or should I just implement two different methods, one as a static, that returns new object and one non-static that modifies itself? Like list.sort() and sorted(list)? But then there is a lot of overhead if I have a lot of methods that modify the object.

Typically, for built-ins the rule is:

1. If the class instances are logically mutable, and the method makes sense as a mutation method, only make mutating methods (and they always return None, so there is no confusion as to whether they returned themselves mutated, or a mutated copy)

2. If the class instances are logically immutable, you have no choice, all such "mutating" methods return new objects (note: New objects of that type typically; rename returning an unrelated list instead of a new Seq would be weird)

Do not have methods that vary in the return like that based on the argument, that's pointlessly confusing, especially if people pass it positionally; quick, what does obj.rename(xyz, True) mean as opposed to obj.rename(xyz, False)? It's more work for you, and more work for them, just don't do it.

Since your class is logically mutable, follow the rules for #1. Don't make a bunch of variant methods though, just define slicing (so they can do myseq[:] for a shallow copy) and/or a copy method (list provides both, you may as well). If the user wants to preserve the original thing, they copy first, then mutate the result. Makes it much clearer in use, and avoids massive code duplication.

It mainly depends on what you want the user to be aware of in your structure.

On one hand, modifying self.seq ensures that you keep entire control of your structure, because you can control how this field is accessed (through properties for example)

On the other hand, returning the collection directly allows the user to make any transformation on it, so you will not keep control of what appends to seq. It can entirely break you class logic if the right checks are not done.