diff --git a/docs/source/howto/migrate-to-v2.rst b/docs/source/howto/migrate-to-v2.rst index 3fde3e02..673f04fb 100644 --- a/docs/source/howto/migrate-to-v2.rst +++ b/docs/source/howto/migrate-to-v2.rst @@ -1,26 +1,55 @@ -How To Migrate to v2.0 +How To Migrate to v2.0 ====================== + .. note:: This guide is still a draft, some details may change The highlight of the *pygls* v2 release is upgrading ``lsprotocol`` to ``v2024.x`` bringing with it support for the proposed LSP v3.18 types and methods. -It also includes standardised object names (so no more classes like ``NotebookDocumentSyncRegistrationOptionsNotebookSelectorType2CellsType``!) +The new version includes standardised object names (so no more classes like ``NotebookDocumentSyncRegistrationOptionsNotebookSelectorType2CellsType``!) +With the major version bump, this release also takes the opportunity to clean up the codebase by removing deprecated code and renaming a few things to try and improve overall consistency. This guide outlines how to adapt an existing server to the breaking changes introduced in this release. **Known Migrations** -You may find insight and inspiration from these projects that have already successfully migrated to v2: +You may find these projects that have already successfully migrated to v2 a useful reference: + +- Our `example servers `__ +- `pytest-lsp `__ +- `esbonio `__ + +Python Support +-------------- + +*pygls v2* removes support for Python 3.8 and adds support for Python 3.13 (with the GIL, you are welcome to try the free-threaded version just note that it has not been tested yet!) + -.. NOTE: The missing link below will be filled in a future PR once we have a stable hash for the commit that updates the example servers. +Removed Deprecated Functions +---------------------------- -- Our `example servers <>`__ +The following methods and functions have been deprecated for some time and have now been removed in *pygls v2*. +================================================== ============== +**pygls v1** **pygls v2** +================================================== ============== +``pygls.workspace.Document`` ``pygls.workspace.TextDocument`` +``pygls.workspace.utf16_unit_offset`` ``TextDocument.position_codec.utf16_unit_offset`` or ``Workspace.position_codec.utf16_unit_offset`` +``pygls.workspace.utf16_num_units`` ``TextDocument.position_codec.client_num_units`` or ``Workspace.position_codec.client_num_units`` +``pygls.workspace.position_from_utf16`` ``TextDocument.position_codec.position_from_client_units`` or ``Workspace.position_codec.position_from_client_units`` +``pygls.workspace.position_to_utf16`` ``TextDocument.position_codec.position_to_client_units`` or ``Workspace.position_codec.position_to_client_units`` +``pygls.workspace.range_from_utf16`` ``TextDocument.position_codec.range_from_client_units`` or ``Workspace.position_codec.range_from_client_units`` +``pygls.workspace.range_to_utf16`` ``TextDocument.position_codec.range_to_client_units`` or ``Workspace.position_codec.range_to_client_units`` +``Workspace.documents`` ``Workspace.text_documents`` +``Worspace.get_document`` ``Workspace.get_text_document`` +``Worspace.put_document`` ``Workspace.put_text_document`` +``Worspace.remove_document`` ``Workspace.remove_text_document`` +``Worspace.update_document`` ``Workspace.update_text_document`` +================================================== ============== -Renamed LanguageServer Methods ------------------------------- +Renamed ``LanguageServer`` Methods +---------------------------------- The :class:`~pygls.lsp.LanuageServer` class has been moved to the ``pygls.lsp`` module:: @@ -32,7 +61,7 @@ The :class:`~pygls.lsp.LanuageServer` class has been moved to the ``pygls.lsp`` from pygls.lsp.server import LanguageServer server = LanguageServer(name="my-language-server", version="v1.0") -All server-side LSP methods are now automatically generated from the specification, as a result the following methods have been renamed +All LSP requests and notifications that can be sent by a server are now automatically generated from the specification, as a result the following methods have been renamed ================================================== ============== **pygls v1** **pygls v2** @@ -364,3 +393,4 @@ If you need to access the underlying protocol object this is now via the ``proto ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ pygls' base server class has been renamed + diff --git a/docs/source/reference/servers.rst b/docs/source/reference/servers.rst index 2c4e7693..ef3294ab 100644 --- a/docs/source/reference/servers.rst +++ b/docs/source/reference/servers.rst @@ -7,7 +7,7 @@ Servers .. autoclass:: pygls.progress.Progress :members: -.. autoclass:: pygls.server.Server +.. autoclass:: pygls.server.JsonRPCServer :members: diff --git a/examples/servers/code_actions.py b/examples/servers/code_actions.py index 5516d314..26fe1ad5 100644 --- a/examples/servers/code_actions.py +++ b/examples/servers/code_actions.py @@ -27,17 +27,7 @@ import re from pygls.lsp.server import LanguageServer -from lsprotocol.types import ( - TEXT_DOCUMENT_CODE_ACTION, - CodeAction, - CodeActionKind, - CodeActionOptions, - CodeActionParams, - Position, - Range, - TextEdit, - WorkspaceEdit, -) +from lsprotocol import types ADDITION = re.compile(r"^\s*(\d+)\s*\+\s*(\d+)\s*=(?=\s*$)") @@ -45,13 +35,13 @@ @server.feature( - TEXT_DOCUMENT_CODE_ACTION, - CodeActionOptions(code_action_kinds=[CodeActionKind.QuickFix]), + types.TEXT_DOCUMENT_CODE_ACTION, + types.CodeActionOptions(code_action_kinds=[types.CodeActionKind.QuickFix]), ) -def code_actions(params: CodeActionParams): +def code_actions(params: types.CodeActionParams): items = [] document_uri = params.text_document.uri - document = server.workspace.get_document(document_uri) + document = server.workspace.get_text_document(document_uri) start_line = params.range.start.line end_line = params.range.end.line @@ -60,21 +50,23 @@ def code_actions(params: CodeActionParams): for idx, line in enumerate(lines): match = ADDITION.match(line) if match is not None: - range_ = Range( - start=Position(line=start_line + idx, character=0), - end=Position(line=start_line + idx, character=len(line) - 1), + range_ = types.Range( + start=types.Position(line=start_line + idx, character=0), + end=types.Position(line=start_line + idx, character=len(line) - 1), ) left = int(match.group(1)) right = int(match.group(2)) answer = left + right - text_edit = TextEdit(range=range_, new_text=f"{line.strip()} {answer}!") + text_edit = types.TextEdit( + range=range_, new_text=f"{line.strip()} {answer}!" + ) - action = CodeAction( + action = types.CodeAction( title=f"Evaluate '{match.group(0)}'", - kind=CodeActionKind.QuickFix, - edit=WorkspaceEdit(changes={document_uri: [text_edit]}), + kind=types.CodeActionKind.QuickFix, + edit=types.WorkspaceEdit(changes={document_uri: [text_edit]}), ) items.append(action) diff --git a/pygls/workspace/__init__.py b/pygls/workspace/__init__.py index 53e9b1f4..c6caae59 100644 --- a/pygls/workspace/__init__.py +++ b/pygls/workspace/__init__.py @@ -1,97 +1,9 @@ -from typing import List -import warnings - -from lsprotocol import types - from .workspace import Workspace from .text_document import TextDocument from .position_codec import PositionCodec -# For backwards compatibility -Document = TextDocument - - -def utf16_unit_offset(chars: str): - warnings.warn( - "'utf16_unit_offset' has been deprecated, instead use " - "'PositionCodec.utf16_unit_offset' via 'workspace.position_codec' " - "or 'text_document.position_codec'", - DeprecationWarning, - stacklevel=2, - ) - _codec = PositionCodec() - return _codec.utf16_unit_offset(chars) - - -def utf16_num_units(chars: str): - warnings.warn( - "'utf16_num_units' has been deprecated, instead use " - "'PositionCodec.client_num_units' via 'workspace.position_codec' " - "or 'text_document.position_codec'", - DeprecationWarning, - stacklevel=2, - ) - _codec = PositionCodec() - return _codec.client_num_units(chars) - - -def position_from_utf16(lines: List[str], position: types.Position): - warnings.warn( - "'position_from_utf16' has been deprecated, instead use " - "'PositionCodec.position_from_client_units' via " - "'workspace.position_codec' or 'text_document.position_codec'", - DeprecationWarning, - stacklevel=2, - ) - _codec = PositionCodec() - return _codec.position_from_client_units(lines, position) - - -def position_to_utf16(lines: List[str], position: types.Position): - warnings.warn( - "'position_to_utf16' has been deprecated, instead use " - "'PositionCodec.position_to_client_units' via " - "'workspace.position_codec' or 'text_document.position_codec'", - DeprecationWarning, - stacklevel=2, - ) - _codec = PositionCodec() - return _codec.position_to_client_units(lines, position) - - -def range_from_utf16(lines: List[str], range: types.Range): - warnings.warn( - "'range_from_utf16' has been deprecated, instead use " - "'PositionCodec.range_from_client_units' via " - "'workspace.position_codec' or 'text_document.position_codec'", - DeprecationWarning, - stacklevel=2, - ) - _codec = PositionCodec() - return _codec.range_from_client_units(lines, range) - - -def range_to_utf16(lines: List[str], range: types.Range): - warnings.warn( - "'range_to_utf16' has been deprecated, instead use " - "'PositionCodec.range_to_client_units' via 'workspace.position_codec' " - "or 'text_document.position_codec'", - DeprecationWarning, - stacklevel=2, - ) - _codec = PositionCodec() - return _codec.range_to_client_units(lines, range) - - __all__ = ( "Workspace", "TextDocument", "PositionCodec", - "Document", - "utf16_unit_offset", - "utf16_num_units", - "position_from_utf16", - "position_to_utf16", - "range_from_utf16", - "range_to_utf16", ) diff --git a/pygls/workspace/workspace.py b/pygls/workspace/workspace.py index 558ec77b..0bd68e5b 100644 --- a/pygls/workspace/workspace.py +++ b/pygls/workspace/workspace.py @@ -19,7 +19,6 @@ import copy import logging import os -import warnings from typing import Dict, Optional, Sequence, Union from lsprotocol import types @@ -96,16 +95,6 @@ def _create_text_document( def add_folder(self, folder: WorkspaceFolder): self._folders[folder.uri] = folder - @property - def documents(self): - warnings.warn( - "'workspace.documents' has been deprecated, use " - "'workspace.text_documents' instead", - DeprecationWarning, - stacklevel=2, - ) - return self.text_documents - @property def notebook_documents(self): return self._notebook_documents @@ -285,39 +274,3 @@ def update_text_document( doc_uri = text_doc.uri self._text_documents[doc_uri].apply_change(change) self._text_documents[doc_uri].version = text_doc.version - - def get_document(self, *args, **kwargs): - warnings.warn( - "'workspace.get_document' has been deprecated, use " - "'workspace.get_text_document' instead", - DeprecationWarning, - stacklevel=2, - ) - return self.get_text_document(*args, **kwargs) - - def remove_document(self, *args, **kwargs): - warnings.warn( - "'workspace.remove_document' has been deprecated, use " - "'workspace.remove_text_document' instead", - DeprecationWarning, - stacklevel=2, - ) - return self.remove_text_document(*args, **kwargs) - - def put_document(self, *args, **kwargs): - warnings.warn( - "'workspace.put_document' has been deprecated, use " - "'workspace.put_text_document' instead", - DeprecationWarning, - stacklevel=2, - ) - return self.put_text_document(*args, **kwargs) - - def update_document(self, *args, **kwargs): - warnings.warn( - "'workspace.update_document' has been deprecated, use " - "'workspace.update_text_document' instead", - DeprecationWarning, - stacklevel=2, - ) - return self.update_text_document(*args, **kwargs)