How can I enforce ASCII-only identifiers in Python while still allowing UTF-8 string literals?

There's no built‑in flag or encoding setting in Python that will only restrict non‐ASCII identifiers while still allowing non‑ASCII content inside string literals. In Python 3, Unicode identifiers are allowed by design (PEP 3131) so that you can write function names or variable names in many languages.

However, if you need to enforce that only ASCII is used in identifiers, you can use one of the following approaches:

---

1. Use a Linter or Static Analyzer

Tools like flake8 or pylint allow you to add custom rules. You could write a plugin or a custom checker that scans the abstract syntax tree (AST) of your source code and raises warnings or errors if any identifier contains non-ASCII characters.

---

2. Create a Custom Preprocessor or Import Hook

You can write a small utility that parses your module’s source code before it’s compiled. Here’s an example using Python’s ast module:

PYTHONCopied
import ast

def check_ascii_identifiers(code, filename="<unknown>"):
    """
    Parse the source code and raise SyntaxError if any identifier contains non-ASCII characters.
    """
    tree = ast.parse(code, filename=filename)
    
    for node in ast.walk(tree):
        # Check function and class names
        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
            if any(ord(c) > 127 for c in node.name):
                raise SyntaxError(f"Non-ASCII identifier in {node.__class__.__name__} '{node.name}' detected in {filename}")
        
        # Check arguments names in function definitions
        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
            for arg in node.args.args:
                if any(ord(c) > 127 for c in arg.arg):
                    raise SyntaxError(f"Non-ASCII identifier in argument '{arg.arg}' detected in {filename}")
            # (Optionally, also check keyword-only arguments, vararg and kwarg)
            if node.args.vararg and any(ord(c) > 127 for c in node.args.vararg.arg):
                raise SyntaxError(f"Non-ASCII identifier in vararg '{node.args.vararg.arg}' detected in {filename}")
            if node.args.kwarg and any(ord(c) > 127 for c in node.args.kwarg.arg):
                raise SyntaxError(f"Non-ASCII identifier in kwarg '{node.args.kwarg.arg}' detected in {filename}")
    
    return tree

if __name__ == "__main__":
    # Example source code
    example_code = '''\
# This should raise an error
def тест():
    pass

# This should work
text = "Привет, мир!"
'''

    try:
        check_ascii_identifiers(example_code, filename="example.py")
    except SyntaxError as e:
        print("SyntaxError:", e)

In this snippet the check_ascii_identifiers function parses the code and walks the AST checking function names, class names, and function argument names. When it finds an identifier with any character having an ordinal above 127 (i.e. non-ASCII), it raises a SyntaxError. You can expand this function to catch additional nodes (e.g., variable names in assignments) as needed.

To integrate this into your workflow, you could either:

• Insert this check at the beginning of your script.
• Write a custom import hook that runs these checks on module load.
• Use it in your continuous integration (CI) pipeline to flag code that doesn't adhere.

---

3. For Jupyter Notebooks

Jupyter doesn’t have a built‑in mechanism to enforce identifier restrictions. However, you can define an IPython cell magic that preprocesses the cell’s source code before execution. For example:

PYTHONCopied
from IPython.core.magic import register_cell_magic
import ast

def check_ascii_identifiers(code, filename="<cell>"):
    tree = ast.parse(code, filename=filename)
    for node in ast.walk(tree):
        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
            if any(ord(c) > 127 for c in node.name):
                raise SyntaxError(f"Non-ASCII identifier in {node.__class__.__name__} '{node.name}' detected")
        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
            for arg in node.args.args:
                if any(ord(c) > 127 for c in arg.arg):
                    raise SyntaxError(f"Non-ASCII identifier in argument '{arg.arg}' detected")
    return tree

@register_cell_magic
def ascii_identifiers(line, cell):
    # Run our check before executing the cell
    check_ascii_identifiers(cell)
    exec(cell, globals())

# Now, in a notebook cell, you can start with:
# %%ascii_identifiers
# def тест():
#     pass
#
# text = "Привет, мир!"

By using this cell magic, the notebook will raise a SyntaxError if a cell contains non-ASCII identifiers while still allowing non-ASCII string literals.

---

Summary

• No built‑in configuration exists: Python’s encoding directives affect the entire file, not just identifiers.
• Custom solutions are required: Either by using a linter/static analyzer or by writing a custom preprocessor/import hook.
• Jupyter Notebooks: Similar techniques—such as a cell magic—can be applied to enforce the restriction.

These approaches let you enforce ASCII-only identifiers while keeping the flexibility of UTF-8 encoded strings.