mmf 设置

这个元项目提供了一种简单的方法来安装我通常使用的所有 python 工具。它还可以作为一个相当简单的例子来设置一个包 tatepip可以安装，并指定依赖项。

特别是，我为以下用例构建了它：

1. 快速安装和配置我需要的工具。例如，我经常使用 CoCalc。每当我创建一个新项目时，我都需要执行一些初始化。有了这个项目，只需使用 [ pipx] 安装这个包，然后使用一些工具。具体来说：

   pipx install mmf-setup
   mmf_setup cocalc mercurial hg-evolve hg-git black
   

   这会执行以下操作，然后将各种配置文件链接到主目录：

   pipx install mmf-setup
   pipx inject mmf-setup mercurial hg-evolve hg-git black
   curl -sSL https://install.python-poetry.org | python3 -
   

2. 在新计算机上初始设置 python 发行版。这涉及更多一点，因为需要先安装 python（我建议使用 Miniconda）然后更新工具。

3. 一个记录安装和设置 python 和相关工具的各个方面的地方。其中一些是旧的，但保留在这里以供参考。

4. 为开发工作设置 sys.path 的通用方法，通过调用mmf_setup.set_path().

   • pyproject.toml更高级别目录中某处的文件中的条目。
   • setup.cfg更高级别目录中某处的文件中的条目。
   • 包含这些文件、setup.py文件.hg 或目录中的任何一个的第一个父.git目录。

快速入门 (TL;DR)

1. 要在无需安装包的情况下获得笔记本初始化功能，只需将nbinit.py复制到您的项目中即可。导入这将尝试执行 import mmf_setup;mmf_setup.nbinit()，但如果失败，将手动运行类似的代码。

2. 使用以下之一从源目录、 PyPI等安装此包：

   • 直接来自 PyPI

     python3 -m pip install --user mmf-setup[nbextensions]
     

   • 从源头

     python3 -m pip install --user
     hg+https://alum.mit.edu/www/mforbes/hg/forbes-group/mmf-setup[nbextensions]
     

   • 从本地源 （解压后从源目录运行它。）

     python3 -m pip install --user .[nbextensions]
     

   注意：这些包​​括nbextensions额外的。--user如果您想在系统范围内而不是在site.USER_BASE.

3. 要获取 Jupyter (IPython) 笔记本的笔记本工具，请在笔记本中执行以下代码单元，然后使用以下命令信任笔记本File/Trust Notebook：

   import mmf_setup; mmf_setup.nbinit()
   

   这将设置在输出单元中实现的主题，以便将其存储以供在线使用，例如通过 NBViewer呈现时。可以指定不同的主题。（目前仅theme='default'受theme='mmf'支持。）

4. Mercurial：如果您想使用hg-git和Evolve 扩展安装 mercurial，那么您可以使用hg额外的：

   python3 -m pip install --user .[hg]
   

   这基本上运行pip install mercurial hg-git hg-evolve。mmf_setup然后，您可以通过以下方式之一获取脚本，在您的环境中启用这些功能：

   eval $"(mmf_setup -v)"     # Enable hg lg but not evolve, etc.
   eval $"(mmf_setup -v -H)"  # Enable evolve, etc.
   mmf_setup -v [-H]          # Shows what will be set set (dry run).
   

   要在您登录时自动执行此操作，请将此行添加到您的~/.bashc或 ~/.bash_profile脚本中。

   警告：该eval $"(mmf_setup -v -H)"选项还包括一个 mercurial 更新挂钩，它将添加%include ../.hgrc到您的项目.hg/hgrc文件中hg > update。这允许您在存储库中包含项目特定的 mercurial 自定义，但存在潜在的安全风险。请参阅下面的讨论。

   这些也可以通过将以下内容添加到您的~/.hgrc文件来手动启用：

   # ~/.hgrc
   ...
   [extensions]
   evolve =
   topics =
   hggit =
   

环境sys.path

使用 python 代码的首选方法是安装它，最好是安装到虚拟环境或 conda 环境中。通过安装它，您将确保您的程序或库通过正确插入到 sys.path 中可用于笔记本等。在开发代码时，还可以进行“可编辑”安装 ，python -m install -e \<path\>以便看到代码更新。

但是，在开发代码时，这可能无法满足所有用例，因此我们提供 mmf_utils.set_path(cwd='.')了将其设置mmf_setup.ROOT并插入到sys.path.

确定的算法ROOT如下cwd（'.' 默认情况下，但可以在调用中指定set_path()）开始。注意：在每种情况下，指定的路径都必须是现有目录，否则将被忽略。

• 指定为 as 的值mmf_setup.ROOT将覆盖所有内容。

• 环境变量中的值MMF_SETUP_ROOT将覆盖其他所有内容。

• ROOT在第一个找到的显式条目pyproject.toml：

  # pyproject.toml
  [tool.mmf_setup]
  ROOT = 'src'
  

• 第一个显式条目setup.cfg：

  # setup.cfg
  [mmf_setup]
  ROOT = src
  

• 包含任何文件setup.py、setup.cfg、 或 pyproject.toml、 或 目录.git、 或的第一个父目录.hg。

如果这些都没有为 生成有效的现有目录ROOT，则不会设置它。

Mercurial (hg) 工具

如果您mmf_setup使用以下之一获取脚本的输出：

eval $"(mmf_setup -v)"
eval $"(mmf_setup -v -H)"

那么您的HGRCPATH将被修改为包括 hgrc.lga或 hgrc.full分别。第一个添加了一个有用的hg lga（hg lg简称）命令，它提供了简洁的图形显示：

$ hg lg
@  200:d michael (64 minutes ago) 0.4.0[0.4.0] tip
|   ENH,DOC,TST,API: Cleaned up set_path...
o  199:d michael (31 hours ago) 0.4.0[0.4.0]
|   WIP,CHK: Cleaning up set_path.
o  198:d michael (20 hours ago) 0.4.0[0.4.0]
|   DOC: Added developer Notes.md
...

第二个版本-H添加了一些有用的扩展：hg-git、Evolve并启用了Topics。例如，后者是与 Heptapod接口所必需的。

最后，该-H选项启用一个挂钩hg update，当您调用. 这是一个潜在的安全风险，因为不受信任的存储库可能在. 因此，在包含以下内容之前，我们需要用户干预：%include ../.hgrc.hg/hgrchg update.hgrc

$ eval $"(mmf_setup -v -H)"
$ hg clone https://alum.mit.edu/www/mforbes/hg/forbes-group/mmf-setup
...
updating to branch default
88 files updated, 0 files merged, 0 files removed, 0 files unresolved
$ cd mmf-setup
$ hg up 0.4.0
Repository .../mmf-setup contains an .hgrc file.
Including this in .hg/hgrc is a potential security risk.
Only do this if you trust the repository.

Include this .hgrc in .hg/hgrc? [yN]y
Adding '%include ../.hgrc' to '.hg/hgrc'
...
$ tail .hg/hgrc
...
%include ../.hgrc

笔记

有关开发人员说明，请参阅Notes.md。关于 python、IPython 等的其他注释存储在docs文件夹中。

变化

0.4.8

• 默认情况下，不要在 CoCalc 上安装 mercurial 等：这些现在包含在默认 Ubuntu 20.04 映像中。如果您需要这些，请明确指定它们：

  mmf-setup cocalc mercurial hg-git hg-evolve jupytext black
  

0.4.7

• 推荐并支持在 CoCalc 上使用 pipx 安装 mmf-setup。
• 使用新的诗歌安装。
• 放弃对 python3.6 的支持。

0.4.6

• 使用 python3 进行 CoCalc 设置。（是 Docker 图像的问题）。
• 忽略 matplotlib 错误。

0.4.3

• 解决了问题 #28：mmf_initial_setup如果存在 .DS_Store 文件，则在 Mac OS X 上失败。
• 解决问题 #29：配置文件中的相对路径解析为绝对路径
• 为运行+的 CoCalc添加了别名findpy,findf等。findafindgrep

0.4.2

• 解决了问题 #26：在 CoCalc 上安装的重大改进。
  • 移动~/.bashrc到~/.bashrc_cocalc以便我们可以插入~/.local/bin到 PATH非登录外壳。这在尝试hg通过 SSH 推送时很重要，它hg无需登录即可运行。我们的新工作流程需要能够hg访问等。以前这是通过使用系统版本evolve更新这些来工作 的，但现在新项目失败了，所以我们已经删除了这个。Python 2hg
  • 添加.hgrc对顶级 cocalc 的调整~.hgrc（现在最好包括hgrc.lga 在这里，以便学生等可以看到这些。但默认情况下不要启用evolve等。）
  • 用户现在应该调用eval "$(mmf_setup -v -H)"而不是使用 source . mmf_setup -H。Sourcingmmf_setup现在会发出弃用警告消息。
  • Cocalc 安装现在以隔离方式进行测试。（只有nox -s test_cocalc 作品……见第 27 期。）
• 使hgrc.fullPOSIX 兼容（使用sh）。（导致 GitHub 工作流程失败。）脚本仍然需要bash在我们调用 run-tests.py.
• 工作 GitHub 工作流程和 cocalc 测试。
• 更新发布流程。

0.4.1

• 使mmf_setup -v输出干净，以便我们可以eval "$(mmf_setup -v)"而不是采购。将来我们将把它变成一个 python 文件，所以这eval将是唯一的选择。
• 修复了nbinit()未定义路径的失败问题。
• 添加了更多测试。

0.4.0

• 解决了问题 #23：放弃对 nbclean mercurial 扩展的支持（难以维护），从而使问题 #1、#3、#8、#9、#11 过时。

• 删除旧的过时笔记本扩展程序（如 Calico 工具、 RISE等）的安装。这些现在都可以使用标准扩展程序或 pip 安装。

  • 用点子：

    python -m pip install jupyter_contrib_nbextensions RISE
    jupyter contrib nbextension install --user
    

  • 使用康达：

    conda install -c conda-forge jupyter_contrib_nbextensions rise
    jupyter contrib nbextension install --user
    

  另请参阅 NBExtensions。

• 改进的测试隔离。

• 的扩展选项mmf_setup。

  • Mercurial 配置现在分两个阶段： 仅使用内置模块安全地hgrc.lga提供命令，其中包括此模块，并激活和扩展。这也适用 于包含文件的钩子，但要求用户确认，因为这是一个安全风险。hg lghgrc.fullhg-gitevolveupdate.hgrc

0.3.1

• mmf_setup cocalc为 CoCalc.com 项目添加了初始化（从 更改mmf_setup smc）。
• 向呼叫添加消息，nbinit()表明 HGROOT 已添加到sys.path.
• 使用 CoCalc 上的 git 用户名类解决问题 #22。

0.3.0

• 支持 python 3 - 放弃对 python 2 的支持。
• Conda 可从 anaconda 云上的 mforbes 频道安装。
• 添加缺少的 default.tex 主题，以便 nbinit() 引入数学定义，即使没有指定主题。
• 修复了 KeyError：asyncioIPython 导入失败时出错。

0.1.13

• 不完整的版本......这里的一切都被卷入0.3.0

0.1.12

• 使mmf_initial_setuppython 3 兼容。
• 添加nbinit()了日志记录并对HGROOT.
• 为 MathJaX添加\D, \sn, \cn,命令。\dn

0.1.11

• 解决问题 #20：
  • mmf_setup.set_path.set_path_from_file允许在 setup.cfg文件中配置路径。
  • 修复 python 3 错误：TypeError: Can't mix strings and bytes in path components

0.1.10

• 为以前的更改添加了更好的向后兼容性。
• 简化 nbinit 主题管理并'default'默认使用主题。
  • 新主题只需要覆盖他们需要的内容。
  • 不要更改默认字体，因为这在 CoCalc 上效果不佳（代码单元格在单击时会改变大小，这很痛苦。）

0.1.9

• 解决问题：

  • #17：商店mmf_setup.HGROOT
  • #18：使用命令进行更安全的异常处理，nbclean因此数据不会丢失
  • #19：nbclean使用新的 mercurial API

• 添加\erfi, \sech,\Braket

• import mmf_setup.set_path.hgroot将添加HGROOT到没有 IPython 的路径

• 添加了独立nbinit.py使用，无需mmf_setup安装。

0.1.8

• 解决问题 #15。
• 用于$BASH_SOURCE{0}获取BIN_DIR（解决问题 #16）
• 添加了添加nbinit(hgroot)选项（问题 #13）hg rootsys.path

0.1.7

• 将选项更改为--clean-all（解决问题 #7）
• 更新了笔记本样式（添加\Tr，修复了输出溢出问题）
• 添加了 pip 选项 mmf_setup[nbextensions]
• 删除'EnableNBExtensionApp'了破坏新 Jupyter 的依赖（解决了问题 #12）
• 添加了一些用于在 Sage Mathcloud (SMC) 上初始化设置的文件（解决问题 #14）。
  • 添加mmf_initial_setup了脚本和一些初始化文件（.inputrc, .hgrc, .bash_aliases）。
  • 运行mmf_setup smc
• 删除了旧的扩展管理器，因为 nbextensions 现在非常好。

0.1.6

• 添加了 cupdate 命令（解决了问题 #4）
• 修复了 ccommit 不接受文件列表的错误（问题 #6）
• 在上下文中发出命令以提供强大的恢复机制（问题 #5）