Restoring .ipynb Format from .py Files: A Content-Based Conversion Approach

Introduction

In data science and machine learning workflows, Jupyter Notebook is widely favored for its interactive environment and visualization capabilities. However, users sometimes encounter issues with accidental file format conversions, such as saving .ipynb files as .py format. In such cases, restoring the original notebook format becomes a common requirement. Based on practical cases, this paper explores an efficient and direct conversion method.

Problem Background

Users typically convert notebooks to Python scripts (.py files) through Jupyter Notebook's export features or third-party tools for version control or code reuse. However, reverse conversion—from .py files back to .ipynb format—is less systematically discussed. When .py files actually contain complete notebook JSON structures, simple file renaming can resolve the issue.

Core Conversion Method

By examining file content, we find that some .py files are not ordinary Python scripts but notebook data stored in JSON format. For example, the user-provided code snippet appears as:

{
   "cell_type": "code",
   "execution_count": 581,
   "metadata": {},
   "outputs": [],
   "source": [
    "def add_trig_slope(data, size = 1, axis = 0, option = 0, random = False, lower_b = -1, upper_b = 2): \n",
    "    \n",
    "    # To make the gradual decline of the fuck you plot\n",
    "    ## sin, cos, tan, sigmoid, other activation functions?\n",
    "    # need to list the option in the doc string\n",
    "    \n",
    "    ## Add a random element\n",
    "    newdata = data.copy()\n",
    "    cols = list(newdata.columns)\n",
    "    funcs = [math.sin, math.cos, math.tan, expit]\n",
    "    func = funcs[option]\n",
    "    if axis == 0:\n",
    "        for col in cols:\n",
    "            newdata.loc[:, col] -= size * (func(cols.index(col)))\n",
    "            if random:\n",
    "                newdata.loc[:,col] -= np.random.uniform(lower_b,upper_b)\n",
    "\n",
    "    elif axis == 1:\n",
    "        for i, node in enumerate(newdata.index):\n",
    "            newdata.loc[node,:] -= size * (func(i))\n",
    "            if random:\n",
    "                newdata.loc[node,:] -= np.random.uniform(lower_b,upper_b)\n",
    "\n",
    "        \n",
    "    return newdata\n",
    "    \n",
    "    "
   ]
}

This indicates that the file is essentially a JSON object, conforming to the .ipynb format specification. Therefore, the conversion steps are as follows:

1. Confirm that the file content is a valid JSON structure.
2. Execute the renaming operation in the command line. For example, in Linux or macOS systems: mv <file>.py <file>.ipynb.
3. In Windows systems, this can be done by right-clicking the file and modifying the extension.

This method avoids complex data parsing and directly utilizes the file system's renaming function to achieve format conversion.

Method Validation and Principle Analysis

Jupyter Notebook files (.ipynb) are essentially JSON files containing metadata, code cells, outputs, and other information. When .py files save this JSON data, their content is identical to .ipynb files, differing only in extension. By renaming, the system recognizes the file as a notebook format, allowing it to open correctly in the Jupyter environment.

Validation methods include: using a text editor to check if the file starts with {, or parsing the file content with Python's json module. For example:

import json
with open('file.py', 'r') as f:
    data = json.load(f)
print(data.keys())  # Should output notebook keys such as 'cells', 'metadata', etc.

If parsing is successful, the file can be safely renamed to .ipynb format.

Comparison of Alternative Tools

In addition to direct renaming, the community offers other conversion tools:

• p2j: After installation via pip install p2j, running p2j myscript.py generates an .ipynb file. It is suitable for converting ordinary Python scripts but may not work for files already containing JSON data.
• jupytext: Supports bidirectional synchronization through jupytext --set-formats ipynb,py <file>.ipynb. It is more suitable for long-term maintenance of synchronized .py and .ipynb files but has slightly more complex configuration.

Compared to these tools, the direct renaming method is faster, requires no additional dependencies, and is particularly applicable when the content is already in JSON format.

Practical Recommendations and Considerations

When applying the renaming method, the following considerations should be noted:

1. Back up the original file to prevent operational errors.
2. Ensure the file content is unmodified, maintaining the integrity of the JSON structure.
3. Open the converted file in Jupyter to verify that code cells and outputs display correctly.
4. For large files, the renaming operation is almost instantaneous, avoiding the time-consuming nature of manual copy-pasting.

If the file fails to open after renaming, it may be due to corrupted content or format mismatch; in such cases, tools like p2j or jupytext can be attempted for repair.

Conclusion

Through file content analysis, we demonstrate a simple and effective method for converting .py to .ipynb: when .py files contain JSON-formatted notebook data, directly renaming the extension can restore the original format. This method is based on the file structure principles of Jupyter Notebook, avoiding the use of complex tools and improving work efficiency. Simultaneously, we compare the applicability of other tools, providing users with a comprehensive solution. In practical applications, it is recommended to combine file validation steps to ensure the reliability of the conversion.