魔Python

这是一个包含对Python 3（尽管对Python 2也有很好的支持）进行偏好设置和语法高亮的软件包。语法与Sublime Text、Atom和Visual Studio Code兼容。它旨在作为默认Python软件包的替代品。

注意VSCode用户：魔Python是Visual Studio Code中默认的Python高亮器。除非你需要最新的版本，否则不要安装它。你不太可能看到任何差异，因为你已经在使用魔Python了。

魔Python正确地高亮了所有Python 3语法特征，包括类型注解、f字符串和正则表达式。它是从头开始构建的，具有鲁棒性和广泛的测试套件。

注释中的类型提示需要配色方案的支持。图中使用的配色方案是Chromodynamics。

安装说明

这旨在作为默认Python软件包的直接替换。

在Atom中，安装MagicPython软件包并禁用内置的language-python软件包。

在Sublime Text中，通过“软件包控制”安装MagicPython软件包，并禁用内置的Python软件包（使用“软件包控制 -> 禁用软件包”，或直接在设置文件中将“Python”添加到“ignored_packages”）。

在VSCode中，从版本0.10.1开始，使用“安装扩展”命令安装MagicPython。

或者，所有编辑器都可以手动安装该软件包

• 将魔Python软件包复制到Sublime/Atom/VSCode用户软件包目录；
• 禁用Python软件包；
• 享受。

变更和改进

这个包背后的主要动机是使用现代Python与其他常用语法高亮器的困难。它们在处理语言90%的情况下做得很好，但在一些非常有用且常被忽视的特征的细微之处却失败了。函数注解通常会以各种方式使高亮器变得疯狂。新引入的关键词和魔术方法被缓慢地整合。另外一个问题是对字符串的高亮，所有原始字符串通常都被假设是正则表达式或由 .format 使用的特殊标记，而 .format 的用途却完全被忽略。在日常生活中遇到所有这些问题最终导致了这个包的创建。

总的来说，核心思想是应该很容易注意到代码中的一些异常或特殊之处。异常或特殊并不一定意味着错误，但确实值得显式关注。

注解

注解不应破坏高亮。与代码或注释一样，它们应该很容易从直观上读取。

一个典型的例子是使用隐式字符串连接在一个字符串注解跨越了多行。多行字符串在用作注解时并不是很理想，因为在注解字符串中可能有奇特的缩进和额外的空白。当然，使用行延续或在隐式的字符串连接中混合注释是没有问题的。所有这些都将按你 expected 的方式在代码的任何其他地方高亮。

def some_func(a,                        # nothing fancy here, yet

              b: 'Annotation: '         # implicitly
                 '"foo" for Foo, '      # concatenated
                 '"bar" for Bar, '      # annotation
                 '"other" otherwise'='otherwise'):

注解的更高级的使用情况是在其中包含复杂的表达式，例如 lambda 函数、元组、列表、字典、集合、列表生成器。诚然，这些都可能用得更少，但当它们被使用时，你可以放心地依靠它们以所有辉煌的细节正常高亮。

# no reason why this should cause the highlighter to break
#
def some_func(a:
                 # annotation starts here
                 lambda x=None:
                    {key: val
                        for key, val in
                            (x if x is not None else [])
                    }
                    # annotation ends here and below is the default for 'a'
                    =42):

结果注解的处理方式与其他表达式相同。没有必要担心函数体看起来会乱七八糟。

# no reason why this should cause the highlighter to break
#
def some_func() -> {
                     'Some',        # comments
                     'valid',       # are
                     'expression'   # good
                   }:

字符串

字符串用于以多种不同的方式处理和展示数据。使高亮器更能适应这些用法可以帮助你集中精力在重要的事情上，而不是在视觉解析上。

原始字符串通常被认为是可以作为正则表达式解释的。这有点问题，因为根据应用，这实际上可能不是最常见的情况。在这种情况下，原始字符串仅仅是其他处理器的输入，在这种情况下，正则表达式特有的高亮会极大地阻碍整体可读性。MagicPython遵循一个约定，即小写 r 前缀表示正则表达式字符串，而大写 R 前缀表示不带特殊正则表达式语义的原始字符串。这个约定适用于所有合法的前缀组合。始终如一，这个语法倾向于 Python 3，因此 Python 2 独有的前缀（即 ur 的一些变化）将被标记为已弃用。

字符串格式化通常只支持 '%-style' 格式化，但是，推荐并且更易读的由 .format 使用的语法被忽略了。使用简单的 {key} 替换字段的优点受到了阻碍，因为在复杂的或长的字符串表达式中，可能不会很容易地确定实际上需要哪些 .format 参数。这就是为什么 MagicPython 在适当的字符串类型内高亮两种字符串格式化语法（因为 bytes 在 Python 3 中没有 .format 方法，所以不会得到特殊的高亮，原始和 unicode 字符串则会）。此外，高亮器还会验证格式是否遵循正确的语法。它可以帮助及早发现复杂格式表达式中的错误。

Python 3.6 的 f 字符串在原声和常规口味中均受支持。其对它们的支持比常规字符串中使用 .format 能做的更强大，因为 f 字符串规范允许以更少的歧义来突出显示它们。

数字字面量

大多数数字只是常规十进制常量，但是任何时间使用八进制、二进制、十六进制或复数字面量时，都值得注意，它们是特殊类型的。Python 2 'L' 整数的突出显示也受支持。

数字字面量中的下划线也受支持（PEP 515，Python 3.6 中引入）

100_000_000_000         0b_1110_0101        0x_FF_12_A0_99

Python 3.5 特性

新关键字 async 和 await 被正确突出显示。目前，这些关键字是新的，还没有被保留，因此 Python 解释器将允许将它们用作变量名。但是，不建议将 async 和 await 用作变量、类、函数或模块名称。由 PEP 492 bring 引入 Python 3.5，它们将在 Python 3.7 中成为正确的关键字。当它们用作函数参数名称时，突出显示它们的状态非常重要，否则可能不会被注意到，并可能导致随后的调试非常复杂。

内置类型和魔法方法

各种内置类型、类、函数以及魔法方法都被突出显示。具体来说，当它们在用户定义中作为名称出现时被突出显示。尽管有类和函数掩盖内置的不是错误，但确实值得引起注意，因此掩盖变成了一种故意的而不是意外行为。

在选择类继承列表中突出显示内置类型使其稍微更容易注意到标准类被扩展的位置。也更容易在早期注意到一些错误（你有没有打错过 Excepiton？）

参数和实参

MagicPython 在使用关键字作为参数/实参名称时突出显示关键字。这适用于 async 和 await 的例子，但这也适用于所有其他关键字。虽然当保留关键字用作标识符名称时，Python 解释器会生成适当的错误消息，但还是值得尽早显示它们，以节省即使是这样小的调试工作。

开发

在 MagicPython 上工作需要 npm 和 node.js。

• 克隆仓库
• 运行 make 来构建本地开发环境
• 运行 make release 来构建 Sublime Text 和 Atom 的语法包（运行 make test 也生成“发布”包）

请注意，我们对语法作用域有一些单元测试。我们将扩展并更新我们的测试语料库。这将使我们能够相信，在更新语法和修复错误时，不易出现微小的不一致。使用 make test 定期运行测试，以在更新语法时进行测试。目前测试文件有两部分，由 3 个空新行隔开：要作用域的代码和必须匹配的结果规范。

如果您打算提交 pull request，请遵循以下指南

• 保持代码行长度小于 80 个字符，这可以提高可读性

• 请使用多行正则表达式，特别是对于任何非平凡情况，如：

  • 正则表达式包含已转义和未转义的括号/括号
  • 正则表达式中存在多个 |
  • 正则表达式中存在多个括号对，尤其是嵌套的
  • 或者正则表达式本身长度超过 35 个字符

• 始终运行 make test 以确保您的更改没有意外的副作用

• 更新单元测试并如有必要添加新的，尽可能使测试案例简短

多个作用域

有时候，需要对同一个匹配组分配多个作用域。务必记住，处理语法规范的引擎显然将作用域的顺序视为重要。然而，同样重要的是要知道不同的规范格式似乎有不同的优先级顺序（最重要的优先或最后）。由于我们试图创建可以编译成多种格式的语法，我们必须选择一种约定，并在编译步骤中必要时进行翻译。因此，我们的约定是最重要的作用域排在首位。

颜色方案

如果您想为MagicPython编写自己的颜色方案，可以在misc/scopes找到我们使用的所有作用域列表。该文件基于语法语法自动生成，因此始终是最新的且详尽无遗。