diff --git a/CHANGELOG.md b/CHANGELOG.md index e79318e..6d46ba0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,15 @@ # CHANGELOG +## Version 0.9.1 + +- Clean up and consolidate many cli help strings +- Removed some of the less popularly used argument shortcuts +- Edited module and class level docstrings +- Removed old/useless code. +- Added `--align` cli flag for piece aligning v1 torrents + +--- + ## Version 0.9.0 - Updates to Documentation. diff --git a/README.md b/README.md index b102623..4d4eb46 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,7 @@ ## 🌐 Overview -A command line interface for creating, reviewing, editing, or verifying bittorrent meta files (`.torrent` files). +A command line interface for creating, reviewing, editing, or verifying bittorrent meta files (`.torrent` files). _`torrentfile`_ is open source, and supports all versions of Bittorrent files, including hybrid meta files. The code base is also importable and can easily be used as a library for creating or manipulating torrent files in external projects. Documentation is available at [https://alexpdev.github.io/torrentfile](https://alexpdev.github.io/torrentfile). @@ -25,8 +25,8 @@ Documentation is available at [https://alexpdev.github.io/torrentfile](https://a ## 🔌 Requirements -- Python 3.6+ -- Tested on Linux, Windows and Mac +- Python 3.6+ +- Tested on Linux, Windows and Mac ## 💻 Install @@ -63,10 +63,7 @@ Apache Software License v2.0 - See [LICENSE]("https://github.com/alexpdev/torren ## 💡 Issues & Requests & PRs If you encounter any bugs or would like to request a new feature please open a new issue. - -> PRs and other contributions are welcome - - +PRs and other contributions that are meaningful and add value to the project are welcome. * * * @@ -80,7 +77,7 @@ Creating a basic torrent file is as easy as using the create subcommand with the torrentfile create /path/to/content ``` -You can add one or more trackers by using any one of `-a`, `--announce` +You can add one or more trackers by using any one of `-a`, `--announce` flags and listing their URL as a space separated list. ```bash @@ -99,10 +96,6 @@ By default **`torrentfile`** displays a progress bar indicating how much of the has already been processed. To turn off this display you can either use `--quiet` mode in as a global flag or you can set the `--prog` flag to 0. -```bash -torrentfile --quiet create /path/to/content -``` - ```bash torrentfile create /path/to/content --prog 0 ``` @@ -132,10 +125,9 @@ For example the following command would create a torrent file at `/some/other/pa torrentfile create /path/to/content -o /some/other/path/ ``` -Bittorrent protocol V1 is still the most commonly used version, therefore _`torrentfile`_ creates -Bittorrent version 1 torrent files by default. To specify creating a V2 file or hybrid (v1 and v2) -use the `--meta-version` followed by the specific version number format to use. The options include: -`1`(v1 default), `2`(v2), or `3`(v1 & v2). +_`torrentfile`_ creates Bittorrent v1 files by default. To create a V2 or hybrid (v1 and v2) +torrent file, use the `--meta-version` option followed by the preferred version number option. +The options include: `1`(v1 default), `2`(v2), or `3`(v1 & v2). ```bash torrentfile create /path/to/content --meta-version 2 @@ -145,17 +137,17 @@ torrentfile create /path/to/content --meta-version 2 torrentfile create /path/to/content --meta-version 3 ``` ->`torrentfile` now includes the option to command line flags for the `create` sub-command from an `ini` style +`torrentfile` includes the option to command line flags for the `create` sub-command from an `ini` style configuration file, by using the `--config` and optional `--config-path` options to specify the path to the configuration file. If `--config-path` is ommited, then `torrentfile` will look by default in the current -working directory for a file named `torrentfile.ini`. If the file is not discovered in the current working directory, -it will move on to look `~/.torrentfile/torrentfile.ini` followed by `~/.config/torrentfile.ini`. Please see the +working directory for a file named `torrentfile.ini`. If the file is not discovered in the current working directory, +it will move on to look `~/.torrentfile/torrentfile.ini` followed by `~/.config/torrentfile.ini`. Please see the [documentation](https://alexpdev.github.io/torrentfile/overview/) for more details on how the configuration file should be formatted. ### Check/Recheck Torrent -The `recheck` subcommand allows you to scan a Bittorrent file and compare it's contents, +The `recheck` subcommand allows you to scan a Bittorrent file and compare it's contents, against a file or directory containing the contents the torrent file was created from. The output provided by this process gives a detailed perspective if any files are missing or have been corrupted in any way. Supports any version of Bittorrent file. @@ -183,7 +175,7 @@ torrentfile edit -h ### Create Magnet To create a magnet URI for a pre-existing torrent meta file, use the sub-command -`magnet` or `m` with the path to the torrent file. +`magnet` with the path to the torrent file. ```bash torrentfile magnet /path/to/some.torrent diff --git a/docs/Source/cli/index.html b/docs/Source/cli/index.html index a1610f9..a223834 100644 --- a/docs/Source/cli/index.html +++ b/docs/Source/cli/index.html @@ -764,7 +764,8 @@

Source code in torrentfile\cli.py - 
71
+        
70
+71
 72
 73
 74
@@ -781,8 +782,7 @@ 

 85
 86
 87
-88
-89
@staticmethod
+88
@staticmethod
 def activate_logger():
     """
     Activate the builtin logging mechanism when passed debug flag from CLI.
@@ -829,7 +829,8 @@ 

 
       

         Source code in torrentfile\cli.py
-        
59
+        
58
+59
 60
 61
 62
@@ -838,8 +839,7 @@ 

 65
 66
 67
-68
-69
@staticmethod
+68
@staticmethod
 def activate_quiet():
     """
     Activate quiet mode for the duration of the programs life.
@@ -942,7 +942,8 @@ 

 
           

             Source code in torrentfile\cli.py
-            
 99
+            
 98
+ 99
 100
 101
 102
@@ -959,8 +960,7 @@ 

 113
 114
 115
-116
-117
def __init__(self,
+116
def __init__(self,
              prog: str,
              width: int = 45,
              max_help_positions: int = 45):
@@ -1070,7 +1070,8 @@ 

 
       

         Source code in torrentfile\cli.py
-        
198
+        
197
+198
 199
 200
 201
@@ -1526,18 +1527,7 @@ 

 651
 652
 653
-654
-655
-656
-657
-658
-659
-660
-661
-662
-663
-664
-665
def execute(args: list = None) -> list:
+654
def execute(args: list = None) -> list:
     """
     Execute program with provided list of arguments.
 
@@ -1566,8 +1556,8 @@ 

         "torrentfile",
         usage="torrentfile <options>",
         description=(
-            "Command line tools for creating, editing, checking, building "
-            "and interacting with Bittorrent meta files"),
+            "Command line tool for creating, editing, validating, building "
+            "and interacting with all versions of Bittorrent files"),
         prefix_chars="-",
         formatter_class=TorrentFileHelpFormatter,
         conflict_handler="resolve",
@@ -1609,13 +1599,12 @@ 

         "create",
         help="Create a new Bittorrent file.",
         prefix_chars="-",
-        aliases=["c", "new"],
+        aliases=["new"],
         formatter_class=TorrentFileHelpFormatter,
     )
 
     create_parser.add_argument(
         "-a",
-        "-t",
         "--announce",
         "--tracker",
         action="store",
@@ -1623,7 +1612,7 @@ 

         metavar="<url>",
         nargs="+",
         default=[],
-        help="One or more space-seperated torrent tracker url(s).",
+        help="one or more space-seperated tracker url(s)",
     )
 
     create_parser.add_argument(
@@ -1631,7 +1620,7 @@ 

         "--private",
         action="store_true",
         dest="private",
-        help="Creates private torrent with multi-tracker and DHT turned off.",
+        help="create private torrent",
     )
 
     create_parser.add_argument(
@@ -1640,7 +1629,7 @@ 

         action="store",
         dest="source",
         metavar="<source>",
-        help="Add a source string. Useful for cross-seeding.",
+        help="add source field to the metadata",
     )
 
     create_parser.add_argument(
@@ -1659,10 +1648,7 @@ 

         action="store",
         metavar="<path>",
         dest="config_path",
-        help="""
-        Use this option in combination with -f or --config
-        options to specify location of config file.
-        """,
+        help="use in combination with --config to provide config file path",
     )
 
     create_parser.add_argument(
@@ -1678,7 +1664,7 @@ 

         action="store",
         dest="comment",
         metavar="<comment>",
-        help="Include a comment in file metadata",
+        help="include a comment in the torrent file metadata",
     )
 
     create_parser.add_argument(
@@ -1687,7 +1673,7 @@ 

         action="store",
         dest="outfile",
         metavar="<path>",
-        help="Explicitly specify the path to write the file .torrent file",
+        help="path to write torrent file",
     )
 
     create_parser.add_argument(
@@ -1698,7 +1684,7 @@ 

         dest="progress",
         metavar="<int>",
         help="""
-        Set the progress bar level.
+        set the progress bar level
         Options = 0, 1
         (0) = Do not display progress bar.
         (1) = Display progress bar.(default)
@@ -1713,8 +1699,8 @@ 

         dest="meta_version",
         metavar="<int>",
         help="""
-        Bittorrent metafile version.
-        Options = 1, 2, 3
+        bittorrent metafile version
+        options = 1, 2, 3
         (1) = Bittorrent v1 (Default)
         (2) = Bittorrent v2
         (3) = Bittorrent v1 & v2 hybrid
@@ -1727,22 +1713,19 @@ 

         dest="piece_length",
         metavar="<int>",
         help="""
-        (Default: auto calculated based on total size of content) Number of
-        bytes for per chunk of data transmitted by Bittorrent client.
-        Acceptable values include integers 14-26 which will be interpreted
-        as exponent for power of 2.  e.g. 14 = 16KiB pieces.
-        Examples:: [--piece-length 14] [--piece-length 20]
+        (Default: auto calculated based on total size of content)
+        acceptable values include numbers 14-26
+        14 = 16KiB, 20 = 1MiB, 21 = 2MiB etc.  Examples:[--piece-length 14]
         """,
     )
 
     create_parser.add_argument(
-        "-w",
         "--web-seed",
         action="store",
         dest="url_list",
         metavar="<url>",
         nargs="+",
-        help="list of web addresses where torrent data exists (GetRight).",
+        help="list of web addresses where torrent data exists (GetRight)",
     )
 
     create_parser.add_argument(
@@ -1751,7 +1734,14 @@ 

         dest="httpseeds",
         metavar="<url>",
         nargs="+",
-        help="list of URLs, addresses where content can be found (Hoffman).",
+        help="list of URLs, addresses where content can be found (Hoffman)",
+    )
+
+    create_parser.add_argument(
+        "--align",
+        action="store_true",
+        help=("Align pieces to file boundaries. "
+              "This option is ignored when not used with V1 torrents."),
     )
 
     create_parser.add_argument(
@@ -1759,15 +1749,14 @@ 

         action="store",
         metavar="<content>",
         nargs="?",
-        help="Path to content file or directory",
+        help="path to content file or directory",
     )
 
-    create_parser.set_defaults(func=create)
+    create_parser.set_defaults(func=commands.create)
 
     edit_parser = subparsers.add_parser(
         "edit",
-        help="""Edit existing torrent meta file.""",
-        aliases=["e"],
+        help="edit torrent file",
         prefix_chars="-",
         formatter_class=TorrentFileHelpFormatter,
     )
@@ -1785,10 +1774,7 @@ 

         dest="announce",
         metavar="<url>",
         nargs="+",
-        help="""
-        Replace current list of tracker/announce urls with one or more space
-        seperated Bittorrent tracker announce url(s).
-        """,
+        help="replace current trackers with one or more urls",
     )
 
     edit_parser.add_argument(
@@ -1797,7 +1783,7 @@ 

         dest="url_list",
         metavar="<url>",
         nargs="+",
-        help="Replace current list of web-seed urls with one or more url(s)",
+        help="replace current web-seed with one or more url(s)",
     )
 
     edit_parser.add_argument(
@@ -1806,19 +1792,19 @@ 

         dest="httpseeds",
         metavar="<url>",
         nargs="+",
-        help="replace all currently listed addresses with new list (Hoffman).",
+        help="replace current http-seed urls with new ones (Hoffman)",
     )
 
     edit_parser.add_argument(
         "--private",
         action="store_true",
-        help="Make torrent private.",
+        help="make torrent private",
         dest="private",
     )
 
     edit_parser.add_argument(
         "--comment",
-        help="Replaces any existing comment with <comment>",
+        help="replaces any existing comment with <comment>",
         metavar="<comment>",
         dest="comment",
         action="store",
@@ -1829,15 +1815,14 @@ 

         action="store",
         dest="source",
         metavar="<source>",
-        help="Replaces current source with <source>",
+        help="replaces current source with <source>",
     )
 
-    edit_parser.set_defaults(func=edit)
+    edit_parser.set_defaults(func=commands.edit)
 
     info_parser = subparsers.add_parser(
         "info",
-        help="Show detailed information about a torrent file.",
-        aliases=["i"],
+        help="show detailed information about a torrent file",
         prefix_chars="-",
         formatter_class=TorrentFileHelpFormatter,
     )
@@ -1846,14 +1831,14 @@ 

         "metafile",
         action="store",
         metavar="<*.torrent>",
-        help="path to pre-existing torrent file.",
+        help="path to torrent file",
     )
 
-    info_parser.set_defaults(func=info)
+    info_parser.set_defaults(func=commands.info)
 
     magnet_parser = subparsers.add_parser(
         "magnet",
-        help="Generate magnet url from an existing Bittorrent meta file.",
+        help="generate magnet url from an existing torrent file",
         aliases=["m"],
         prefix_chars="-",
         formatter_class=TorrentFileHelpFormatter,
@@ -1862,7 +1847,7 @@ 

     magnet_parser.add_argument(
         "metafile",
         action="store",
-        help="Path to Bittorrent meta file.",
+        help="path to torrent file",
         metavar="<*.torrent>",
     )
 
@@ -1883,12 +1868,12 @@ 

         metavar="<int>",
     )
 
-    magnet_parser.set_defaults(func=get_magnet)
+    magnet_parser.set_defaults(func=commands.get_magnet)
 
     check_parser = subparsers.add_parser(
         "recheck",
-        help="Gives a detailed look at how much of the torrent is available.",
-        aliases=["check", "r"],
+        help="gives a detailed look at how much of the torrent is available",
+        aliases=["check"],
         prefix_chars="-",
         formatter_class=TorrentFileHelpFormatter,
     )
@@ -1907,7 +1892,7 @@ 

         help="path to content file or directory",
     )
 
-    check_parser.set_defaults(func=recheck)
+    check_parser.set_defaults(func=commands.recheck)
 
     rebuild_parser = subparsers.add_parser(
         "rebuild",
@@ -1951,7 +1936,7 @@ 

         help="path to where torrents will be re-assembled",
     )
 
-    rebuild_parser.set_defaults(func=rebuild)
+    rebuild_parser.set_defaults(func=commands.rebuild)
 
     rename_parser = subparsers.add_parser(
         "rename",
@@ -1964,18 +1949,13 @@ 

         "target",
         action="store",
         metavar="<target>",
-        help="path to file that needs renaming.",
+        help="path to torrent file",
     )
 
-    rename_parser.set_defaults(func=rename)
+    rename_parser.set_defaults(func=commands.rename)
 
     all_commands = [
-        "c",
-        "e",
-        "i",
         "m",
-        "r",
-        "-i",
         "-h",
         "-V",
         "new",
@@ -2027,11 +2007,11 @@ 

 
       

         Source code in torrentfile\cli.py
-        
671
-672
-673
-674
-675
def main() -> None:
+        
660
+661
+662
+663
+664
def main() -> None:
     """
     Initiate main function for CLI script.
     """
diff --git a/docs/Source/edit/index.html b/docs/Source/edit/index.html
index 699818e..2e01a25 100644
--- a/docs/Source/edit/index.html
+++ b/docs/Source/edit/index.html
@@ -461,13 +461,6 @@